Led 3.0 Class Library DocumentationLed 3.0 Class Library DocumentationDiscontiguousRun < DATA > DiscontiguousRunElement < DATA > LED_DECLARE_DONT_USE_BLOCK_ALLOCATIONLED_DECLARE_USE_BLOCK_ALLOCATIONLED_TCHAR_OFLed_BlockAllocated < T > Led_RefCntPtr < T > Led_SDK_CharLed_SDK_StringLed_SDK_TCHAROFLed_SmallStackBuffer < T > Led_StackBasedHandleLockerLed_URLDLed_URLManagerLed_tCharLed_tStringLedTickCount2XTimeLed_ANSI2SDKStringLed_ANSIString2tStringLed_AssertLed_AssertMemberLed_AssertNotNilLed_BeepNotifyLed_EnsureLed_EnsureMemberLed_EnsureNotNilLed_GetAssertionHandlerLed_GetDoubleClickTimeLed_GetTickCountLed_Get_BadFormatDatException_HandlerLed_Get_OutOfMemoryException_HandlerLed_Get_ThrowOSErrException_HandlerLed_NEltsOfLed_NextCharLed_PreviousCharLed_RequireLed_RequireMemberLed_RequireNotNilLed_SDKString2ANSILed_SDKString2tStringLed_SetAssertionHandlerLed_Set_BadFormatDatException_HandlerLed_Set_OutOfMemoryException_HandlerLed_Set_ThrowOSErrException_HandlerLed_SkrunchOutSpecialCharsLed_ThrowBadFormatDataExceptionLed_ThrowIfErrorHRESULTLed_ThrowIfNullLed_ThrowIfOSErrLed_ThrowIfOSStatusLed_ThrowOSErrLed_ThrowOutOfMemoryExceptionLed_VerifyLed_tString2ANSIStringLed_tString2SDKStringLed_tStrlenLed_tStrnCmpLed_tStrniCmpSyncronizeLedXTickCountValidateTextForCharsetConformancegBeepNotifyCallBackProcSupport defines, and utility functions that should usually be provided by some other class library (e.g. Stroika, TCL, MFC, OWL, etc. These defines should just thunk down to the appropriate class library defines - where possible.
DiscontiguousRun < DATA > [public]
An ordered list of DiscontiguousRunElement. The ordering is very important. The 'fOffsetFromPrev'
is the offset in marker-positions the data is intended to be from the end of the previous element. For the first
element - this if the offset from the 'beginning'.
NB: I would PREFER to have declared this as a typedef - so I would get the vector<> ctors for free. But I couldn't figure out how to declare it in a way that made MSVC60 happy. So I settled for this.
DiscontiguousRunElement < DATA > [public]
We frequently need to keep track of runs of data. Sometimes - those elements are discontiguous. This template is merely used to give us a uniform naming convention for how we deal with those runs.
These elements are meant to be used with DiscontiguousRun.
LED_DECLARE_DONT_USE_BLOCK_ALLOCATION [public]
If you subclass from a class which uses block-allication, you can use this to turn off block allocation in your particular subclass.
See also LED_DECLARE_USE_BLOCK_ALLOCATION and Led_BlockAllocated.
LED_DECLARE_USE_BLOCK_ALLOCATION [public]
This helper macro can be used to avoid some of the C++ gorp required in declaring that you are using block-allocation with a given class.
See also - LED_DECLARE_DONT_USE_BLOCK_ALLOCATION and Led_BlockAllocated.
LED_TCHAR_OF [public]
Like the Win32SDK macro _T(). Except is based on the Led type Led_tChar, and the Led
macro qLed_CharacterSet.
Led_BlockAllocated < T > [public]
Led_BlockAllocated<T> is a templated class designed to allow easy use
of a block-allocated memory strategy. This means zero overhead malloc/memory allocation for fixed
size blocks (with the only problem being the storage is never - or almost never - returned to the
free store - it doesn't leak - but cannot be used for other things). This is often a useful
tradeoff for things you allocate a great number of.
You shouldn't disable it lightly. But you may wish to temporarily disable block-allocation
while checking for memory leaks by shutting of the qAllowBlockAllocation compile-time configuration variable.
Note also - you can avoid some of the uglines of the overload declarations by using the
LED_DECLARE_USE_BLOCK_ALLOCATION macro.
Led_RefCntPtr < T > [public]
A very simple reference counted pointer implementation. Alas - there doesn't seem to be anything in STL which provides this functionality! AutoPtr is closest, but no cigar.
This implementation would be slightly more efficient, and slightly less flexible, if we assumed T had a base-class which contained the reference count. Right now, places where I'm using this don't warrant the worry about efficiency.
NB: - we do allow for a refCntPtr to be NULL. But any call to GetRep() assert its non-null. Check with call to IsNull() first if you aren't sure.
Led_SDK_Char [public]
See Led_SDK_String
Led_SDK_String [public]
Expands to either the ANSI string or the ANSI wstring class, depending on the
value of the configuration define qSDK_UNICODE.
This is rarely used - but is used for things like font names, and other system IO strings that may need to be in one format or another.
Led_SDK_TCHAROF [public]
Like the Win32SDK macro _T(). See Led_SDK_String.
Led_SmallStackBuffer < T > [public]
Often times in Led I must copy a bunch of characters to operate on them as an array (say when I'm computing word wrap info, for example). But the number of characters can vary, depending on the particular text you've entered. But it ALMOST ALWAYS would fit nicely in a little stack buffer. But you cannot GAURANTEE that is safe.
In steps Led_SmallStackBuffer<T>. Just declare one of these, and it
automaticlly uses the stack for the buffer if it will fit, and silently allocates heap memory
and returns it to the free store on stack based destruction if needed. Use it just like you
would a stack-based array. You don't need to know about this to use any of Led's APIs, but its
a helpful class you may want to use elsewhere in your code.
Led_StackBasedHandleLocker [public]
A utility class to lock (and on exit from the block unlock) a handle.
Led_URLD [public]
Led_URLD is an abstraction of the Netscape Web Browser URL object.
At least thats where the name comes from. And some of its more quirky attributes.
This object has two attributes, a URL and a title.
It has accessors to convert it into and from the Netscape URLD object format (URLD on mac
and "Netscape Bookmark" on windows; same thing).
It also can easily be used for dealing with URLs with ActiveX/Microsoft URL representations.
See also, Led_URLManager
Led_URLManager [public]
Led_URLManager is a utility class to deal with opening URLs.
Depending on the OS you are running Led with, it can be configured to use
DDE, ActiveX, ShellExec, AppleEvents, or
Internet Config (IC).
By default, it uses all that make sense for the given operating system in some reasonable
order (prefering more robust approaches, and those that work more frequently and those that
report better errors).
This class also provides a utility - FileSpecToURL - to make a URL object
from a full path name.
See also, Led_URLD
Led_tChar [public]
There are lots of different ways of encoding character sets. And it is a goal for Led to be able to support them all. The three major ways are wide characters, single-byte characters, and multibyte character strings.
Led_tChar is a basic type used throughout Led. In the
case of single byte character systems it is a char, and this also corresponds
to a character. In mutlibyte character systems, it is also of type char,
but then it does NOT correspond to a character. Rather some consecutive sequence
of Led_tChars specify a character. And for wide character sets (e.g UNICODE),
Led_tChar is of type wchar_t, and - like with single byte
character sets - does contain a full character.
Now simply supporting one of these would be easy. Support all three within the
same code base requires a small amount of discipline. It requires that we never assume that
sizeof (char) == sizeof (Led_tChar) - because that supposed equality is not true.
And it requires that we not assume that every possible Led_tChar pointer
refers to a valid character beginning. Instead, we must use utility routines
Led_NextChar and
Led_PreviousChar to navigate through
Led_tChar* strings.
All of Led's APIs which refer to characters or bytes or any such thing really
refer to Led_tChars (actually, typically Led_tChar*).
All of Led's APIs gaurantee (unless otherwise noted) that they will never split a character
(return a character offset which points in the middle of a multibyte character).
And all of Led's APIs similarly require that all offsets and strings passed to
it consist of valid character boundaries.
You can always use (and Led does many asserts internally)
ValidateTextForCharsetConformance() to check / validate a string to make
sure it is valid with respect to the character set you are using (for example doesn't end
spliting a multibyte character).
Led_tString [public]
This expands to either the ANSI C++ string class library class string
or wstring - depending on whether we are using UNICODE or not. It is a basic_string
templated on Led_tChar.
unsigned long LedTickCount2XTime (float ledTickCount)
X-Windows specific. See also SyncronizeLedXTickCount and Led_GetTickCount. Maps Led_GetTickCount ()
result to the sort of time value you can stick into an XEvent record.
Led_SDK_String Led_ANSI2SDKString (const string& s);
Led_ANSIString2tString [public]
Led_tString Led_ANSIString2tString (const string& s);
#define Led_Assert(c) {if (!(c)) { _Led_Debug_Trap_ (__FILE__, __LINE__); }}
#define Led_AssertMember(p,c) Led_Assert (dynamic_cast < c* > (p) != NULL)
#define Led_AssertNotNil(p) Led_Assert (p!=NULL)
void Led_BeepNotify ()
Make an audible beep on the users terminal. Used as a simple warning mechanism (like for typing bad characters).
NB: For X-Windows only, this function invokes the private gBeepNotifyCallBackProc callback procedure to handle the beeping. This is because with X-Windows, the beep callback requires data (XDisplay) we don't have at this level.
#define Led_Ensure(c) {if (!(c)) { _Led_Debug_Trap_ (__FILE__, __LINE__); }}
#define Led_EnsureMember(p,c) Led_Ensure (dynamic_cast < c* > (p) != NULL)
#define Led_EnsureNotNil(p) Led_Ensure (p!=NULL)
Led_GetAssertionHandler [public]
void (*Led_GetAssertionHandler ()) (const char* fileName, int lineNum);
Led makes very heavy use of assertions (to some extent inspired and patterend after Bertrand Meyers Eiffel assertion mechanism). Assertions are logical statements about function parameters, results, object states, etc, which are guaranteed (required) to be held true. These logical assertions serve two important functions: they document the requirements on input parameters for a function, and the promises made on function return. And they perform this documentation task in such a way that the compiler can generate special code (conditionally) to verify that the assertions hold true.
This latter point about conditional compilation is important. If the macro preprocessor
symbol qDebug is true (non-zero), then this assertion cheching is enabled. If the symbol
is false (zero), then the checking is disabled. Of course the promises must always hold true! But
since the checking can significantly slow the code, it is best to only build with assertions on in certain
circumstances (like while developing, and for much of QA/testing); but for released products it shouldbe
disabled so the editor operates at maximum speed.
Led's assertion mechanism is not only present to help debug Led itself. After all, that would have little value to a user of the Led class library. It is also very helpful to a programmer using the class library. This is because nearly all the parameters passed to Led functions are immediately checked for validity, so mistakes are trapped as early as possible. If you pass bad values to a Led function, you will very likely get a debugger trap at almost exactly the point in your calling code where the error occured. This can make debugging code written using Led much easier.
Led provides four familes of 'assertion' macro functions. The are named
Assert,
Require,
Ensure, and
Verify.
The familily you will most often be interested in is Requires.
This is because these are used to check parameters validity on entry to a function. So typically
when you see a Require fail, you will find that it is the calling function which is passing
invalid arguments to the function which triggered the requirement failure. The other reason Requires
will be of particular interest to programmers using Led is because checking the Require declarations
at the beggining of a function is often very telling about the details of what sort of parameters the function expects.
Probably the next most common sort of assertion you will see is Ensures. These state promises about the return values of a function. These should very rarely be triggered (if they are , they almost always indicate a bug in the function that triggered the Ensure failure). But the reason they are still of interest to programmers using Led is because they document what can be assumed about return values from a particular function.
Plain Assertions are for assertions which don't fall into any of the above categories, but are still useful checks to be performed. When an assertion is triggered, it is almost always diagnostic of a bug in the code which triggered the assertion (or corrupted data structures). (asside: Assertions logically mean the same thing as Ensures, except that Ensures only check return values).
Verifys are inspired by the MFC VERIFY() macro, and the particular idiosyncracies
of the Win32 SDK, though they can be used cross-platform. Many of the Win32 SDK routines return non-zero
on success, and zero on failure. Most sample Win32 code you look at simply ignores these results. For
paranoia sake (which was very helpful in the old moldy win32s days) I wrap most Win32 SDK calls in a
Led_Verify wrapper. This - when debugging is enabled - checks the return value,
and asserts if there is a problem. Very Important: Unlike the other flavors of Assertions, Verify
always evaluates its argument!.
This last point is worth repeating, as it is the only source of bugs I've ever seen introduced
from the use of assertions (and I've seen the mistake more than once). All flavors of assertions
(except Verify) do NOT evaluate their arguments if qDebug is off. This means you cannot
count on the arguments to assertions having any side-effects. Use Led_Verify instead of the other
assertion flavors if you want to only check for compliance if qDebug is true, but want
the side-effect to happen regardless.
Now when assertions are triggered, just what happens? Here I think there is only one sensible answer. And that is that the program drops into the debugger. And what happens after that is undefined. This is Led's default behavior.
But there are others who hold the view that triggered assertions should
generate exceptions. This isn't an appropraite forum for explanations of why this is generally
a bad idea. Instead, I simply provide the flexability to allow those who want todo this
that ability. There are Led_SetAssertionHandler and Led_GetAssertionHandler
functions which allow the programmer to specify an alternate assertion handling scheme. The
only assumption Led mkaes about this scheme is that the assertion handling funciton not return
(so itmust either exit the program, or longjump/throw). Led makes no gaurantee that attempts
to throw out past an assertion will succeed.
Led_GetDoubleClickTime [public]
float Led_GetDoubleClickTime ()
Returns the amount of time (in seconds) between clicks which the OS deems should be interpretted as a double click.
float Led_GetTickCount ()
Get the number of seconds since some constant, system-specified reference time. This is used to tell how much time has elapsed since a particular event.
Note - though this is based on the same reference time as an time values packed into event records, it maybe differently normalized. These times are all in seconds, whereas event records are often in other units (ticks - 1/60 of a second, or milliseconds).
In the case of X-Windows - this business is very complicated because there are two different times
one might be intersted in. There is the time on the client (where Led is running) and the time on the X-Server
(users computer screen). Alas - X11R4 appears to have quite weak support for time - and offers no way I've found
to accurately get the time from the users computer. As a result - with X-Windows - you must arrange to call
SyncronizeLedXTickCount for each event that specifies a time value (as soon as that event arrives). This
data - together with time values from the client (where Led is running) computer will be used to provide a
better approximation of the true elapsed time.
Led_Get_BadFormatDatException_Handler [public]
void (*Led_Get_BadFormatDataException_Handler ()) ();
Get the handler used in Led_ThrowBadFormatDataException.
Led_Get_OutOfMemoryException_Handler [public]
void (*Led_Get_OutOfMemoryException_Handler ()) ();
Get the handler used in Led_ThrowOutOfMemoryException.
Led_Get_ThrowOSErrException_Handler [public]
void (*Led_Get_ThrowOSErrException_Handler ()) (OSErr err);
Get the handler used in Led_ThrowBadFormatDataException.
#define Led_NEltsOf(X) sizeof(X)/sizeof(X[0])
Trivial wrapper on sizeof () to get n-elts of a C++ array
Led_tChar* Led_NextChar (Led_tChar* fromHere);
See Led_tChar
Led_tChar* Led_PreviousChar (Led_tChar* startOfString, Led_tChar* fromHere);
See Led_tChar
#define Led_Require(c) {if (!(c)) { _Led_Debug_Trap_ (__FILE__, __LINE__); }}
#define Led_RequireMember(p,c) Led_Require (dynamic_cast < c* > (p) != NULL)
#define Led_RequireNotNil(p) Led_Require (p!=NULL)
string Led_SDKString2ANSI (const Led_SDK_String& s);
Led_SDKString2tString [public]
Led_tString Led_SDKString2tString (const Led_SDK_String& s);
Led_SetAssertionHandler [public]
void Led_SetAssertionHandler (void (*assertionHandler) (const char* fileName, int lineNum));
Led_Set_BadFormatDatException_Handler [public]
void Led_Set_BadFormatDataException_Handler (void (*badFormatDataExceptionCallback) ());
Set the handler used in Led_ThrowBadFormatDataException.
Note - any handler supplied must never return - it must always throw.
Led_Set_OutOfMemoryException_Handler [public]
void Led_Set_OutOfMemoryException_Handler (void (*outOfMemoryHandler) ());
Set the handler used in Led_ThrowOutOfMemoryException.
Note - any handler supplied must never return - it must always throw.
Led_Set_ThrowOSErrException_Handler [public]
void Led_Set_ThrowOSErrException_Handler (void (*throwOSErrExceptionCallback) (OSErr err));
Set the handler used in Led_ThrowBadFormatDataException.
Note - any handler supplied must never return - it must always throw.
Led_SkrunchOutSpecialChars [public]
size_t Led_SkrunchOutSpecialChars (Led_tChar* text, size_t textLen, Led_tChar charToRemove)
This function is useful to remove embedded NUL-characters from a string, or any other such undesirable characters. Returns NEW length of string (after removals). Removes in place.
Led_ThrowBadFormatDataException [public]
void Led_ThrowBadFormatDataException ();
This is called internally by Led (or your code) when some data is found to be in a bad format.
Either your class library will call this to specify a class-lib specific exception type for this kind of error, or you can in your application. Or just leave it todo the default.
Note - this method never returns - it always throws.
See also Led_ThrowOutOfMemoryException.
Led_ThrowIfErrorHRESULT [public]
void Led_ThrowIfErrorHRESULT (HRESULT hr);
If the HRESULT failed, then throw that HRESULT.
void Led_ThrowIfNull (void* p);
If p == NULL, then Led_ThrowOutOfMemoryException.
void Led_ThrowIfOSErr (OSErr err)
If the argument err is not noErr, then throw that error.
void Led_ThrowIfOSStatus (OSStatus err)
If the argument err is not noErr, then throw that error.
void Led_ThrowOSErr (OSErr err);
This is called internally by Led (or your code) after MacOS system calls that return an OSErr.
By default that error # is thrown - but you can override this behavior by calling Led_Set_ThrowOSErrException_Handler.
Note - this method never returns - it always throws, unless 'err' == 'noErr' - in which case it does nothing.
Led_ThrowOutOfMemoryException [public]
void Led_ThrowOutOfMemoryException ();
Even though Standard C++ defines how this SHOULD behave, many class libraries (e.g. MFC and PowerPlant) expect non-C++-Standard things to get thrown when you run out of memory.
So - Led internally calls this routine for out of memory exceptions.
The behavior of this routine detaults to the C++ standard, unless you are using some class library, like
PowerPlant or MFC. Then those modules may call Led_Set_OutOfMemoryException_Handler. You can call Led_Get_OutOfMemoryException_Handler
or Led_Set_OutOfMemoryException_Handler to get/set the handler.
Note - this method never returns - it always throws.
#if qDebug
Led_Verify () is an assertion like Led_Assert, except its argument is ALWAYS EVALUATED, even if debug is OFF. This is useful for cases where you just want todo an assertion about the result of a function, but don't want to keep the result in a temporary just to look at it for this one assertion test...
Led_tString2ANSIString [public]
string Led_tString2ANSIString (const Led_tString s);
Led_tString2SDKString [public]
Led_SDK_String Led_tString2SDKString (const Led_tString& s);
size_t Led_tStrlen (const Led_tChar* s);
Expands to any of the ANSI C++ functions, std::strlen ()/wcslen/_mbstrlen(not ansiC++), depending on
macro qLed_CharacterSet.
size_t Led_tStrnCmp (const Led_tChar* l, const Led_tChar* r, size_t n);
Expands to any of the ANSI C++ functions, std::strncmp/etc, depending on
macro qLed_CharacterSet.
size_t Led_tStrniCmp (const Led_tChar* l, const Led_tChar* r, size_t n);
Expands to any of the ANSI C++ functions, std::strnicmp/etc, depending on
macro qLed_CharacterSet.
SyncronizeLedXTickCount [public]
void SyncronizeLedXTickCount (unsigned long xTickCount)
X-Windows specific magic. See Led_GetTickCount.
ValidateTextForCharsetConformance [public]
bool ValidateTextForCharsetConformance (const Led_tChar* text, size_t length); // just return true or false - no other diagnostics
See Led_tChar
gBeepNotifyCallBackProc [public]
void (*gBeepNotifyCallBackProc) () = NULL;
X-Windows specific magic. See Led_BeepNotify.
Return to Led Page
Return to Led ClassLib Documentation Index
Return to Led Reference Manual Index