Functions and Macros


Functions

AllocColor
Assert
BEGINDISPATCH
BEGINDISPATCHPROC
BEGINFORM
Caution
DECLAREDISPATCH
DECLAREFORM
DISPATCHFORM
DISPATCHTABLE
DrawBitmap
DrawResBitmap
DrawXBitmap
DrawXIcon
ENDDISPATCH
ENDFORM
ESwapDouble
ESwapFloat
ESwapLong
ESwapWord
EmptyRect
EqualRect
Error
GETHIWORD
GETLOWORD
GetResourceData
GetResourceMessage
InitCursorAnimation
InsetRect
MAKEDWORD
Message
NSwapDouble
NSwapFloat
NSwapLong
NSwapWord
NormalCursor
OPT_MACOS
OPT_NATIVEORDER
OPT_WINOS
OPT_XWIN
OffsetRect
PtInRect
PtToRect
RegisterView
RegisterViewID
RegisterWindow
RegisterWindowID
SectRect
SetCursorID
SetRect
SwapDouble
SwapFloat
SwapLong
SwapWord
UnionRect
WaitCursor
Warning
cvtc2p
cvtp2c
pstrcat
pstrcmp
pstrcpy
vyformat
yformat


AllocColor

Header: <XDraw.h>

Usage: unsigned long AllocColor(Color c)

(X) Allocate a color. This finds the color if it was already asked for from the X server. This is used internally by YAAF.


Assert

Header: <XError.h>

Usage: Assert(conditional)

This macro expands to a function which handles program asserts. If there is a problem, this throws an error and unwinds, rather than halting the program


BEGINDISPATCH

Header: <XEvent.h>

Usage: BEGINDISPATCH(classID,baseClassID)

This is a shorthand macro for declaring the event dispatch table for the specified class. The base class of that class must also be provided so that if the event is not found in this table, the table of the base class can also be searched.

The contents of this table are provided by using one or more DISPATCHTABLE macros, and the table is ended with ENDDISPATCH.


BEGINDISPATCHPROC

Header: <XEvent.h>

Usage: BEGINDISPATCHPROC(classID,baseClassID,dispatchProcPtr)

This is a shorthand macro for declaring the event dispatch table for the specified class. The base class of that class must also be provided so that if the event is not found in this table, the table of the base class can also be searched.

The contents of this table are provided by using one or more DISPATCHTABLE macros, and the table is ended with ENDDISPATCH.

This is a variant of the BEGINDISPATCH macro, but which also provides a pointer to a function in the class which receives all messages.


BEGINFORM

Header: <XForm.h>

Usage: BEGINFORM(classID)

This macro is the shorthand macro for constructing the form event dispatch table. This is used to build the table; the contents of the table is made by one or more DISPATCHFORM macros, and ended with the ENDFORM macro.


Caution

Header: <XError.h>

Usage: bool Caution(unsigned long msg,...)

This puts up a 'caution' alert which has two buttons: 'Ok' and 'Cancel.' If 'Cancel' is pressed, this will return true


DECLAREDISPATCH

Header: <XEvent.h>

Usage: DECLAREDISPATCH

This notes in this particular class the declarations needed to make the BEGINDISPATCH/ENDDISPATCH stuff. If your XGDispatch- derived event handling class actually handles events, you would insert this macro into the class declaration in your header file.


DECLAREFORM

Header: <XForm.h>

Usage: DECLAREFORM

For a form using this method of dispatching messages, this provides a good shorthand for declaring the dispatch proc


DISPATCHFORM

Header: <XForm.h>

Usage: DISPATCHFORM(message,method)

This macro constructs the contents of a form event dispatch table, the table associated with dispatching events for an XGForm object. The table is started with BEGINFORM, and ended with ENDFORM


DISPATCHTABLE

Header: <XEvent.h>

Usage: DISPATCHTABLE(messageID,messageProc)

Declares a single entry in the event dispatch table. This is how you declare the contents of the dispatch table created using BEGINDISPATCH or BEGINDISPATCHPROC


DrawBitmap

Header: <XDrawData.h>

Usage: void DrawBitmap(XGDraw&draw,void*data,short x,short y,bool trans)

(X) This is the routine used to draw a bitmap onto the display surface specified


DrawResBitmap

Header: <XDrawData.h>

Usage: void DrawResBitmap(HDC dest,short resID,short x,short y)

(Windows) Draw the bitmap specified from a resource file. This loads it myself, thus preserving the color information for the bitmap


DrawXBitmap

Header: <XDrawData.h>

Usage: void DrawXBitmap(XGDraw&draw,short resID,short x,short y)

(X) Draw the bitmap. This gets the bitmap from the 'bmap' resource


DrawXIcon

Header: <XDrawData.h>

Usage: void DrawXIcon(XGDraw&draw,short resID,short x,short y)

(X) Draw the icon. This is identical to the above (and means that my icons are small bitmaps), but the resource comes from the 'icon' resource identifier


ENDDISPATCH

Header: <XEvent.h>

Usage: ENDDISPATCH

Ends the event dispatch table declared using BEGINDISPATCH or BEGINDISPATCHPROC


ENDFORM

Header: <XForm.h>

Usage: ENDFORM

This macro ends a form event dispatch table. Use BEGINFORM to start the table for an XGForm object, and DISPATCHFORM for building the contents.


ESwapDouble

Header: <XDataUtil.h>

Usage: ESwapDouble(word)

This macro swaps the word order for a non-network order word to the native order of the target environment. Depending on the setting of OPT_NATIVEORDER, this either swaps or does not swap the bytes in word.

This is reliant on the size of a double being 8 bytes. This also relies on the double being in IEEE format; use with caution.


ESwapFloat

Header: <XDataUtil.h>

Usage: ESwapFloat(word)

This macro swaps the word order for a non-network order word to the native order of the target environment. Depending on the setting of OPT_NATIVEORDER, this either swaps or does not swap the bytes in word.

This is reliant on the size of a float being 4 bytes. This also relies on the double being in IEEE format; use with caution.


ESwapLong

Header: <XDataUtil.h>

Usage: ESwapLong(word)

This macro swaps the word order for a non-network order word to the native order of the target environment. Depending on the setting of OPT_NATIVEORDER, this either swaps or does not swap the bytes in word.


ESwapWord

Header: <XDataUtil.h>

Usage: ESwapWord(word)

This macro swaps the word order for a non-network order word to the native order of the target environment. Depending on the setting of OPT_NATIVEORDER, this either swaps or does not swap the bytes in word.


EmptyRect

Header: <XDrawData.h>

Usage: bool EmptyRect(Rect*r)

Return true if the rectangle is empty


EqualRect

Header: <XDrawData.h>

Usage: bool EqualRect(Rect*a,Rect*b)

Return true if rectangles are equal


Error

Header: <XError.h>

Usage: void Error(unsigned long msg,...)

This puts up an error alert and returns immediately, rather than throwing an exception.


GETHIWORD

Header: <XDataUtil.h>

Usage: GETHIWORD(longword)

This macro returns the high order word from a long-word, and is the inverse of the MAKEDWORD macro.


GETLOWORD

Header: <XDataUtil.h>

Usage: GETLOWORD(longword)

This macro returns the low order word from a long-word, and is the inverse of the MAKEDWORD macro.


GetResourceData

Header: <XDataUtil.h>

Usage: extern void*GetResourceData(long resType,short resID)

This is an X specific routine used for getting resources.

A note about this routine. While I am declaring it in this header, the GetResourceData routine itself is actually generated by the RCompile tool, along with the resource data that is associated with this program.

If you fail to compile the resources into a resource.c file and link it in with the rest of your YAAF program, this routine will show up as missing. Likewise, if there is a problem with your resources (like duplicate resources), you will have problems compiling the resource.c file.


GetResourceMessage

Header: <XDataUtil.h>

Usage: short GetResourceMessage(short res,short index,char*smsg,char*lmsg)

This returns two strings, the short string and the long string for the resource ID specified. Normally this is used for errors and warnings; the short string is the title, the long string is the explanation. The long message will be no more than 256 characters (including the null terminator)

In order to simplify porting to various operating systems, I use a standard custom resource format generated by CompileMessages


InitCursorAnimation

Header: <XCursorUtil.h>

Usage: void InitCursorAnimation(short*l)

Initialize the cursor animation sequence. This is an optional call with an array of cursor resource numbers which is repeatedly sequenced through as WaitCursor() is called.


InsetRect

Header: <XDrawData.h>

Usage: void InsetRect(Rect*r,short x,short y)

Inset the rectangle by the delta values provided. If the values are negative, this expands the rectangel instead.


MAKEDWORD

Header: <XDataUtil.h>

Usage: MAKEDWORD(highword,loword)

This macro concatenates two word-sized objects into a long-word sized object.


Message

Header: <XError.h>

Usage: void Message(const char*title,const char*smsg,const char*lmsg,...)

Even weaker than warning, this doesn't even go through the post error mechanism.


NSwapDouble

Header: <XDataUtil.h>

Usage: NSwapDouble(word)

This macro swaps the word order for a network order word to the native order of the target environment. Depending on the setting of OPT_NATIVEORDER, this either swaps or does not swap the bytes in word.

This is reliant on the size of a double being 8 bytes. This also relies on the double being in IEEE format; use with caution.


NSwapFloat

Header: <XDataUtil.h>

Usage: NSwapFloat(word)

This macro swaps the word order for a network order word to the native order of the target environment. Depending on the setting of OPT_NATIVEORDER, this either swaps or does not swap the bytes in word.

This is reliant on the size of a float being 4 bytes. This also relies on the double being in IEEE format; use with caution.


NSwapLong

Header: <XDataUtil.h>

Usage: NSwapLong(word)

This macro swaps the word order for a network order word to the native order of the target environment. Depending on the setting of OPT_NATIVEORDER, this either swaps or does not swap the bytes in word.


NSwapWord

Header: <XDataUtil.h>

Usage: NSwapWord(word)

This macro swaps the word order for a network order word to the native order of the target environment. Depending on the setting of OPT_NATIVEORDER, this either swaps or does not swap the bytes in word.


NormalCursor

Header: <XCursorUtil.h>

Usage: void NormalCursor(void)

Restore the prior cursor after a wait cursor loop


OPT_MACOS

Header: <XConfig.h>

Usage: #if OPT_MACOS == 1

This macro is defined to be 1 if the YAAF libraries are being compiled on the Macintosh. This is set by examining the various compiler-defined macros defined by the Metrowerks Codewarrior compiler.

If you are recompiling the YAAF libraries using another Macintosh compiler, it's worth examining the code in <XConfig.h> to convert it apporpriately.


OPT_NATIVEORDER

Header: <XConfig.h>

Usage: #if OPT_NATIVEORDER == 1

This macro is defined to be 1 if the byte order for integers is in network-native (Macintosh) order, or 0 if otherwise. This is set in the <XConfig.h> header.


OPT_WINOS

Header: <XConfig.h>

Usage: #if OPT_WINOS == 1

This macro is defined to be 1 if the YAAF libraries are being compiled on Microsoft Windows. This is set by examining the various compiler-defined macros defined by the Metrowerks Codewarrior compiler and by the Microsoft Visual C++ compiler.

If you are recompiling the YAAF libraries using another Windows compiler, it's worth examining the code in <XConfig.h> to convert it apporpriately.


OPT_XWIN

Header: <XConfig.h>

Usage: #if OPT_XWIN == 1

This macro is defined to be 1 if the YAAF libraries are being compiled on the Macintosh. This is set as command line arguments in the Unix makefile.


OffsetRect

Header: <XDrawData.h>

Usage: void OffsetRect(Rect*r,short x,short y)

Offset the rectangle by the delta values (x,y)


PtInRect

Header: <XDrawData.h>

Usage: bool PtInRect(Point pt,Rect*r)

Is this point inside this rectangle?


PtToRect

Header: <XDrawData.h>

Usage: void PtToRect(Point a,Point b,Rect*r)

Create rectangle which contains these two points.


RegisterView

Header: <XGView.h>

Usage: RegisterView(class)

Macro which uses template to register with factory. This version of the macro assumes the class is a descendant of the XGView class with a constructor that takes a parent XGObject class and an XGArgStream, and has the class type defined as an enumeration variable of 'kClassID'.


RegisterViewID

Header: <XGView.h>

Usage: RegisterViewID(classType,class)

Macro which uses template to register with factory. This version of the macro assumes the class is a descendant of the XGView class with a constructor that takes a parent XGObject class and an XGArgStream. The creator code is provided as one of the arguments in this macro.


RegisterWindow

Header: <XWindow.h>

Usage: RegisterWindow(class)

This macro expands into the template method call to register this window class with the XGWindowFactory class.


RegisterWindowID

Header: <XWindow.h>

Usage: RegisterWindowID(type,class)

This macro expands into the template method call to register this window class with the XGWindowFactory class. The type which this window is is the first parameter


SectRect

Header: <XDrawData.h>

Usage: bool SectRect(Rect*a,Rect*b,Rect*out)

Intersect two rectangles. if empty, return false


SetCursorID

Header: <XCursorUtil.h>

Usage: void SetCursorID(short id)

Sets the current cursor to the one specified. This is stored away so that the specified cursor can be redisplayed after a wait sequence.


SetRect

Header: <XDrawData.h>

Usage: void DrawXIcon(XGDraw&draw,short resID,short x,short y)

Set the rectangle based on the four coordinates


SwapDouble

Header: <XDataUtil.h>

Usage: double SwapDouble(double c)

Swap the byte order of this 8 byte double.


SwapFloat

Header: <XDataUtil.h>

Usage: float SwapFloat(float c)

Swap this 4 byte floating point value


SwapLong

Header: <XDataUtil.h>

Usage: unsigned long SwapLong(unsigned long c)

Swap this four byte word


SwapWord

Header: <XDataUtil.h>

Usage: unsigned short SwapWord(unsigned short c)

Swap this 2 byte word


UnionRect

Header: <XDrawData.h>

Usage: void UnionRect(Rect*a,Rect*b,Rect*out)

Find the largest enclosing rectangle


WaitCursor

Header: <XCursorUtil.h>

Usage: void WaitCursor(void)

Wait cursor. This spins the cursor animation sequence if any, or else just puts up the standard 'wait' cursor if no sequence was provided.


Warning

Header: <XError.h>

Usage: void Warning(unsigned long msg,...)

This puts up a 'warning' alert, similar to the error alert box. This returns immediately after the box is closed.


cvtc2p

Header: <XDataUtil.h>

Usage: void WaitCursor(void)

Convert a string from C to Pascal. Returns the Pascal string.


cvtp2c

Header: <XDataUtil.h>

Usage: char*cvtp2c(char*dest,const unsigned char*src)

Convert from Pascal to C format string. Returns the C string.


pstrcat

Header: <XDataUtil.h>

Usage: unsigned char*pstrcat(unsigned char*dest,const unsigned char*src)

Concatenate source string to the end of the dest string.


pstrcmp

Header: <XDataUtil.h>

Usage: long pstrcmp(const unsigned char*a,const unsigned char*b)

Compare two pascal strings. This works like the C string compare


pstrcpy

Header: <XDataUtil.h>

Usage: unsigned char*pstrcpy(unsigned char*dest,const unsigned char*src)

Pascal string copy operation.


vyformat

Header: <XDataUtil.h>

Usage: void vyformat(char*out,const char*msg,va_list vlist)

Formatting. The character formatting information is as:

#(N)[SPLXI]

N is the argument number (1..9) 'S' formats strings, 'P' formats pascal strings 'L' formats long integers 'X' formats long integers as hex 'I' formats long integers as characters


yformat

Header: <XDataUtil.h>

Usage: void yformat(char*out,const char*msg,...)

This is the variable argument version of vyformat. This is similar in idea to sprintf(), in that you can print a string with formatting escapes corrisponding to the arguments following.