## 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.