From 2c85a3ccc0e5bc2d3d1ecf42d6066c658efcc354 Mon Sep 17 00:00:00 2001 From: Bill Currie Date: Sun, 10 Jul 2011 17:33:43 +0900 Subject: [PATCH] Make a start on documenting the gui stuff. --- ruamoko/include/gui/Group.h | 33 ++++- ruamoko/include/gui/InputLine.h | 236 +++++++++++++++++++++++++++++--- ruamoko/include/gui/Pic.h | 5 + ruamoko/include/gui/Point.h | 5 + ruamoko/include/gui/Rect.h | 5 + ruamoko/include/gui/Size.h | 5 + ruamoko/include/gui/Slider.h | 5 + ruamoko/include/gui/Text.h | 5 + ruamoko/include/gui/View.h | 8 ++ 9 files changed, 285 insertions(+), 22 deletions(-) diff --git a/ruamoko/include/gui/Group.h b/ruamoko/include/gui/Group.h index d5b8eb903..b9ea99386 100644 --- a/ruamoko/include/gui/Group.h +++ b/ruamoko/include/gui/Group.h @@ -3,17 +3,44 @@ #include "View.h" +/** \addtogroup gui */ +//@{ + @class Array; +/** A group of logically realted views. + + The sub-views are all positioned relative to the group's origin. + Sub-views may be other groups. + + The order in which views are added determines the draw and event handling + order. + + \todo Events are not handled. +*/ @interface Group : View { Array *views; } -- (void) dealloc; + +/** Add a view to the group. + + \param aView The view to be added. + \return The added view. +*/ - (View*) addView: (View*)aView; + +/** Add an array of views to the group. + + The views will be appened to any already existing sub-views, maintaining + the order of the views in the array. + + \param viewlist The array of views to be added. + \return self +*/ - (id) addViews: (Array*)viewlist; -- (void) moveTo: (int)x y:(int)y; -- (void) draw; @end +//@} + #endif//__ruamoko_gui_Group_h diff --git a/ruamoko/include/gui/InputLine.h b/ruamoko/include/gui/InputLine.h index a6b2e48ea..1aafb6302 100644 --- a/ruamoko/include/gui/InputLine.h +++ b/ruamoko/include/gui/InputLine.h @@ -3,38 +3,187 @@ #include "View.h" -struct _inputline_t {}; // opaque type :) +/** \defgroup inputline Low level intputline interface. + \ingroup gui + + Interface functions to the engine implementation. +*/ +//@{ + +/** Opaque handle to an inputline. + + \warning Not a real pointer. Dereferencing leads to nasal-dragon + infested lands. +*/ typedef struct _inputline_t *inputline_t; -@extern inputline_t (int lines, int size, int prompt) InputLine_Create; -@extern void InputLine_SetPos (inputline_t il, int x, int y); -@extern void InputLine_SetCursor (inputline_t il, int cursorr); -@extern @overload void InputLine_SetEnter (inputline_t il, void (f)(string, void*), void *data); -@extern @overload void InputLine_SetEnter (inputline_t il, IMP imp, id obj, SEL sel); -@extern void (inputline_t il, int width) InputLine_SetWidth; -@extern void (inputline_t il) InputLine_Destroy; -@extern void (inputline_t il, int save) InputLine_Clear; -@extern void (inputline_t il, int ch) InputLine_Process; -@extern void (inputline_t il) InputLine_Draw; -@extern void (inputline_t il, string str) InputLine_SetText; -@extern string (inputline_t il) InputLine_GetText; +/** Create a new inputline. + The inputline will be positioned at 0,0 with the cursor enabled. + + \param lines The number of lines of input history. + \param size The maximum length of the input string. + \param prompt The prompt to display. + \return The inputline handle. +*/ +@extern inputline_t InputLine_Create (int lines, int size, int prompt); + +/** Set the visual location of the input line. + + The coordinates are defined by the display system (pixels for clients, + character cells for servers). + + \param il The inputline handle. + \param x The X coordinate of the upper-left corner of the inputline. + \param y The Y coordinate of the upper-left corner of the inputline. +*/ +@extern void InputLine_SetPos (inputline_t il, int x, int y); + +/** Turn the inputline's cursor on or off. + + \param il The inputline handle. + \param cursor 0 turns off the cursor, non-0 turns it on. +*/ +@extern void InputLine_SetCursor (inputline_t il, int cursor); + +/** Set the callback function for when the enter key is pressed. + + \param il The inputline handle. + \param f The callback function. The first parameter is the text + of the input line and the second is \a data. + \param data Pointer to a data block to be passed to the callback + function. +*/ +@extern @overload void InputLine_SetEnter (inputline_t il, void (f)(string, void*), void *data); + +/** Set the callback method for when the enter key is pressed. + + The method will be called with a single string parameter representing the + text of the inputline. eg: + + -enter: (string) text; + + \param il The inputline handle. + \param imp The implementation of the method. + \param obj The object receiving the message. + \param sel The selector representing the message. +*/ +@extern @overload void InputLine_SetEnter (inputline_t il, IMP imp, id obj, SEL sel); + +/** Set the visible width of the inputline. + + \param il The inputline handle. + \param width The width of the inputline in character cells. +*/ +@extern void InputLine_SetWidth (inputline_t il, int width); + +/** Destroy an inputline, freeing its resources. + + \param il The inputline handle. +*/ +@extern void InputLine_Destroy (inputline_t il); + +/** Clear the inputline's text. + + \param il The inputline handle. + \param save If true, the current text will be saved to the history. +*/ +@extern void InputLine_Clear (inputline_t il, int save); + +/** Process a keystroke. + + \param il The inputline handle. + \param key The Quake key code for the key press. +*/ +@extern void InputLine_Process (inputline_t il, int key); + +/** Draw the inputline to the screen. + + Drawing is handled by the engine. + \param il The inputline handle. +*/ +@extern void InputLine_Draw (inputline_t il); + +/** Set the text of the inputline + + \param il The inputline handle. + \param str The text to which the inputline will be set. +*/ +@extern void InputLine_SetText (inputline_t il, string str); + +/** Retrieve the text of the inputline. + + \param il The inputline handle. + \return The current text of the intputline. +*/ +@extern string InputLine_GetText (inputline_t il); +//@} + +/** \addtogroup gui */ +//@{ + +/** Class representation of the low-level inputline objects. +*/ @interface InputLine: View { - inputline_t il; + inputline_t il; ///< The inputline handle. } +/** Initialize. + + \note The size of the bounds parameter is interpreted differently to + usual. The width is in character cells and the hight is used + for the number of lines of history. + \param aRect The bounds of the inputline. + \param char The prompt character. + \todo the size thing is stupid and broken. +*/ - (id) initWithBounds: (Rect)aRect promptCharacter: (int)char; -- (void) setBasePosFromView: (View *) view; -- (void) setWidth: (int)width; -- (void) setEnter: obj message:(SEL) msg; -- (void) cursor: (BOOL)cursor; -- (void) draw; +/** Set the visible width of the inputline. + \param width The visible width of the inputline. + \todo the size thing is stupid and broken. +*/ +- (void) setWidth: (int)width; + +/** Set up the XXX for when the enter key is pressed. + + The method will be called with a single string parameter representing the + text of the inputline. eg: + + -enter: (string) text; + + \param obj The object receiving the message. + \param sel The selector representing the message. + + \todo -(void) set[X]Action: (SEL)aSelector; + \todo -(void) setTarget: (id)ahnObject; +*/ +- (void) setEnter: obj message:(SEL) msg; + +/** Turn the inputline's cursor on or off. + + \param cursor 0 turns off the cursor, non-0 turns it on. +*/ +- (void) cursor: (BOOL)cursor; + +/** Process a keystroke. + + \param key The Quake key code for the key press. +*/ - (void) processInput: (int)key; +/** Set the text of the inputline + + \param text The text to which the inputline will be set. +*/ - (id) setText: (string)text; + +/** Retrieve the text of the inputline. + + \return The current text of the intputline. +*/ - (string) text; @end @@ -43,16 +192,65 @@ typedef struct _inputline_t *inputline_t; { InputLine *input_line; } + +/** Initialize. + + \note The size of the bounds parameter is interpreted differently to + usual. The width is in character cells and the hight is used + for the number of lines of history. + \param aRect The bounds of the inputline. + \param char The prompt character. + \todo the size thing is stupid and broken. +*/ - (id) initWithBounds: (Rect)aRect promptCharacter: (int)char; +/** Set the visible width of the inputline. + + \param width The visible width of the inputline. + \todo the size thing is stupid and broken. +*/ - (void) setWidth: (int)width; + +/** Set up the target/action for when the enter key is pressed. + + The method will be called with a single string parameter representing the + text of the inputline. eg: + + -enter: (string) text; + + \param obj The object receiving the message. + \param sel The selector representing the message. + + \todo -(void) set[X]Action: (SEL)aSelector; + \todo -(void) setTarget: (id)ahnObject; +*/ - (void) setEnter: obj message:(SEL) msg; + +/** Turn the inputline's cursor on or off. + + \param cursor 0 turns off the cursor, non-0 turns it on. +*/ - (void) cursor: (BOOL)cursor; +/** Process a keystroke. + + \param key The Quake key code for the key press. +*/ - (void) processInput: (int)key; +/** Set the text of the inputline + + \param text The text to which the inputline will be set. +*/ - (id) setText: (string)text; + +/** Retrieve the text of the inputline. + + \return The current text of the intputline. +*/ - (string) text; @end +//@} + #endif //__ruamoko_gui_InputLine_h diff --git a/ruamoko/include/gui/Pic.h b/ruamoko/include/gui/Pic.h index d50aed866..f19e8b6e4 100644 --- a/ruamoko/include/gui/Pic.h +++ b/ruamoko/include/gui/Pic.h @@ -3,6 +3,9 @@ #include "gui/View.h" +/** \addtogroup gui */ +//@{ + @interface Pic : View { string pic_name; @@ -15,4 +18,6 @@ -(void)draw; @end +//@} + #endif//__ruamoko_gui_Pic_h diff --git a/ruamoko/include/gui/Point.h b/ruamoko/include/gui/Point.h index 845aafda9..4ac36391a 100644 --- a/ruamoko/include/gui/Point.h +++ b/ruamoko/include/gui/Point.h @@ -1,6 +1,9 @@ #ifndef __ruamoko_gui_Point_h #define __ruamoko_gui_Point_h +/** \addtogroup gui */ +//@{ + struct Point { int x; int y; @@ -12,4 +15,6 @@ typedef struct Point Point; @extern Point addPoint (Point a, Point b); @extern Point subtractPoint (Point a, Point b); +//@} + #endif //__ruamoko_gui_Point_h diff --git a/ruamoko/include/gui/Rect.h b/ruamoko/include/gui/Rect.h index 70d5c4c80..145815d66 100644 --- a/ruamoko/include/gui/Rect.h +++ b/ruamoko/include/gui/Rect.h @@ -4,6 +4,9 @@ #include "gui/Point.h" #include "gui/Size.h" +/** \addtogroup gui */ +//@{ + struct Rect { Point origin; Size size; @@ -27,4 +30,6 @@ typedef struct Rect Rect; - (Rect) offsetBySize: (Size)aSize; #endif +//@} + #endif //__ruamoko_gui_Rect_h diff --git a/ruamoko/include/gui/Size.h b/ruamoko/include/gui/Size.h index 344ee7c4d..0f6b387a3 100644 --- a/ruamoko/include/gui/Size.h +++ b/ruamoko/include/gui/Size.h @@ -1,6 +1,9 @@ #ifndef __ruamoko_gui_Size_h #define __ruamoko_gui_Size_h +/** \addtogroup gui */ +//@{ + struct Size { int width; int height; @@ -12,4 +15,6 @@ typedef struct Size Size; @extern Size addSize (Size a, Size b); @extern Size subtractSize (Size a, Size b); +//@} + #endif //__ruamoko_gui_Size_h diff --git a/ruamoko/include/gui/Slider.h b/ruamoko/include/gui/Slider.h index f077ceda9..13a68f492 100644 --- a/ruamoko/include/gui/Slider.h +++ b/ruamoko/include/gui/Slider.h @@ -3,6 +3,9 @@ #include "View.h" +/** \addtogroup gui */ +//@{ + @interface Slider: View { int index; @@ -16,4 +19,6 @@ @end +//@} + #endif //__ruamoko_gui_Slider_h diff --git a/ruamoko/include/gui/Text.h b/ruamoko/include/gui/Text.h index 8b4051976..d9c6a1311 100644 --- a/ruamoko/include/gui/Text.h +++ b/ruamoko/include/gui/Text.h @@ -3,6 +3,9 @@ #include "View.h" +/** \addtogroup gui */ +//@{ + @interface Text: View { @public @@ -15,4 +18,6 @@ - (void) draw; @end +//@} + #endif //__ruamoko_gui_Text_h diff --git a/ruamoko/include/gui/View.h b/ruamoko/include/gui/View.h index 6b598534b..a84f05e06 100644 --- a/ruamoko/include/gui/View.h +++ b/ruamoko/include/gui/View.h @@ -4,6 +4,12 @@ #include "Object.h" #include "gui/Rect.h" +/** \defgroup gui GUI goo for gooey chewing +*/ + +/** \addtogroup gui */ +//@{ + /** The View class. */ @interface View: Object @@ -28,4 +34,6 @@ - (int) keyEvent:(int)key unicode:(int)unicode down:(int)down; @end +//@} + #endif //__ruamoko_gui_View_h