ARM Club 3

home *** CD-ROM | disk | FTP | other *** search

/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / programming / vista_1 / !Manual_manual_objects < prev next >

Wrap

Text File | 1996-01-27 | 18.6 KB | 554 lines

<html> <title>Objects</title> <h1>Objects</h1> A Window in Vista can contain a number of 'Objects'. These are things which reside inside the window are need to be redrawn. Icons are effectively objects which are handled by the WIMP. An object is created inside a window and every time the window needs redrawn (for a resize or scroll) the objects are asked to redraw themselves by the Window. They are passed the <b>WORK AREA</b> coordinates within the window which needs updated. They can be used to perform clipping of the redraw in order to make it more efficient. <p> Objects in a window has a priority assicoated with them. This is to allow objects to overlap. A higher priority object will receive events such as mouse clicks and key presses before lower priority ones. <p> <h2>Synopsis</h2> <pre> class Object { public: <a href="file:objects#ct">Object</a> (Window *w, char *name, int priority = 0, char *menu = 0) ; virtual <a href="file:objects#dt">~Object</a>() ; virtual void <a href="file:objects#redraw">redraw</a> (int x0, int y0, int x1, int y1) ; virtual void <a href="file:objects#update">update</a> (int x0, int y0, int x1, int y1) ; virtual int <a href="file:objects#compare">compare</a> (int x, int y) ; virtual void <a href="file:objects#move1">move</a> (int x0, int y0, int x1, int y1) ; virtual void <a href="file:objects#move2">move</a> (int dx, int dy) ; virtual void <a href="file:objects#drag">drag</a> (int mx, int my, int buttons) ; virtual void <a href="file:objects#end_drag">end_drag</a> (int x0, int y0, int x1, int y1, int id) ; virtual void <a href="file:objects#click">click</a>(int mx, int my, int button) ; virtual void <a href="file:objects#key">key</a> (int x, int y, int height, int index, int code) ; virtual void <a href="file:objects#double_click">double_click</a> (int mx, int my, int buttons) ; virtual void <a href="file:objects#select">select</a>() ; virtual void <a href="file:objects#unselect">unselect</a>() ; virtual int <a href="file:objects#width">width</a>() ; virtual int <a href="file:objects#height">height</a>() ; virtual void <a href="file:objects#pointer">pointer</a> (int entering) ; virtual void <a href="file:objects#mode_change">mode_change</a>() ; Menu *<a href="file:objects#display_menu">display_menu</a> (int x, int y, int button, int icon) ; virtual void <a href="file:objects#pre_menu">pre_menu</a>(Menu *m, int x, int y, int button, int icon) ; virtual char *<a href="file:objects#get_menu">get_menu</a> (int x, int y, int button, int icon) ; virtual void <a href="file:objects#menu">menu</a> (MenuItem items[]) ; virtual char (<a href="file:objects#help">help</a> (int mx, int my, int buttons) ; int <a href="file:objects#x0">x0</a> ; int <a href="file:objects#x0">y0</a> ; int <a href="file:objects#x0">x1</a> ; int <a href="file:objects#x0">y1</a> ; Window *<a href="file:objects#window">window</a> ; Menu *<a href="file:objects#default_menu">default_menu</a> ; Object *<a href="file:objects#next">next, *prev</a> ; char <a href="file:objects#name">name</a>[32] ; int <a href="file:objects#priority">priority</a> ; int <a href="file:objects#selected">selected</a> ; } ; </pre> <p> <h2>Members</h2> <p> <a name="ct"></a> <h3>Object::Object (Window *w, char *name, int priority = 0, char *menu = 0)</h3> This is the Object constructor. The parameters are: <p> <ul> <li><b>w</b>: The window in which the object exists <li><b>name</b>: The name of the object (a text string - may be "") <li><b>priority</b>: The priority of the object. This determines the order in which the object is placed in the window. Higher priority objects are handled as if they are "on top" of other objects and therefore are first to be given mouse clicks. They are also the first to be redrawn. <li><b>menu</b>: A menu to use as default if the object responds to menu clicks. </ul> <p> <a name="dt"></a> <h3>Object::~Object()</h3> This is the object destructor. It will remove the object from the window. <p> <a name="redraw"></a> <h3>Object::redraw (int x0, int y0, int x1, int y1)</h3> This function is called when the object may need to be redrawn. The function should check if the object boundary box lies within the coordinates passed before redrawing itself. The background has already been cleared by the WIMP. <p> The object can check the coordinates using the following code: <pre> if (x0 <= this->x1 && x1 >= this->x0 && y0 <= this->y1 && y1 >= this->y0) { // redraw the object } </pre> The coordinates passed are window coordinates (not screen coordinates), but can be converted to screen coordinates by code such as: <pre> sx = window->x0 + this->x0 - window->scx ; // screen x sy = window->y1 + this->y0 - window->scy ; // screen y </pre> or by calling the Window functions <a href="file:window#coords">xtoscreen(), ytoscreen()</a>. <p> <a name="update"></a> <h3>Object::update (int x0, int y0, int x1, int y1)</h3> This function is called when the user has requested an update of the window by use of the Wimp_UpdateWindow call. The coords passed are window coordinates (as in redraw). The window is not cleared to the background colour. <p> <a name="compare"></a> <h3>Object::compare (int x, int y)</h3> This function is called to check if the coordinates passed (in screen coordinates this time) are within the object's boundary. <p> In the simplest case, the following code is provided as part of the Object base class. It simply compares the bounding box of the object. If the object is not a simple box, more complex code is required: <pre> int Object::compare (int x, int y) { x = x + (window->scx - window->x0) ; // x in window coords y = y + (window->scy - window->y1) ; // y in window coords return x <= this->x1 && x >= this->x0 && y <= this->y1 && y >= this->y0 ; } </pre> <p> <a name="move1"></a> <h3>Object::move (int x0, int y0, int x1, int y1)</h3> This function moves the object to a new position (in window coordinates). It also allows the object's bounding box to be resized. <p> <a name="move2"></a> <h3>Object::move (int dx, int dy)</h3> This function moves the object a certain distance from its current position. The deltas are in the x and y direction and are in window coordinates. <p> <a name="drag"></a> <h3>Object::drag (int mx, int my, int buttons)</h3> This function begins an object drag. The default function as provided by the Object base class starts a drag by using the do_drag function in the window. <p> <a name="end_drag"></a> <h3>Object::end_drag (int x0, int y0, int x1, int y1, int id)</h3> This function is called by the Task when the drag operation has completed. It is passed the drag bounding box coordinates (screen coordinates) and an integral identifier passed to the dragger. The default function provided by the Object base class moves the object to the new position. <p> <a name="click"></a> <h3>Object::click(int mx, int my, int button)</h3> This function is called when the user clicks select over the object. The parameters passed are exactly as returned from Wimp_Poll for this event. <p> Note that the window must have an appropriate button type for this event to be received. <p> <a name="key"></a> <h3>Object::key (int x, int y, int height, int index, int code)</h3> This function is called when the user presses a key over the object. The paramaters passed are as returned from Wimp_Poll. <p> <a name="double_click"></a> <h3>Object::double_click (int mx, int my, int buttons)</h3> This function is called when the user has double-clicked the mouse over the object. Note that the window must have an appropriate button type for this event to be received. <p> <a name="select"></a> <h3>Object::select()</h3> Mark the object as selected. The selection state can be read by accessing the variable 'selected' within the object class. <p> <a name="unselect"></a> <h3>Object::unselect()</h3> Mark the object as not selected. The selection state can be read by accessing the variable 'selected' within the object class. <p> <a name="width"></a> <h3>Object::width()</h3> Return the width of the object in OS units. <p> <a name="height"></a> <h3>Object::height()</h3> Return the height of the object in OS units. <p> <a name="pointer"></a> <h3>Object::pointer (int entering)</h3> This is called when the mouse has entered or exited the object. This is equivalent to the function of the same name in the Window class. See <a href="file:window#pointer">Window::pointer</a>. <p> <a name="mode_change"></a> <h3> Object::mode_change()</h3> This is invoked when the screen mode has been changed. <p> <a name="display_menu"></a> <h3> Object::display_menu (Menu *m, int x, int y, int button, int icon)</h3> This function is used to display a menu for this object. If the object has been created with a default menu, this will be displayed. Otherwise the function get_menu will be called. If the default menu is being displayed, the function pre_menu will be called in order to allow the user to change the default menu. <p> <a name="pre_menu"></a> <h3> Object::pre_menu (Menu *m, int x, int y, int button, int icon)</h3> This virtual function is called just before a menu is displayed on the screen. The purpose is to allow the user to change the contents of the menu. <p> <a name="get_menu"></a> <h3> Object::get_menu (int x, int y, int button, int icon)</h3> This is called when there was no default menu provided to the constructor. It is a virtual function which should be supplied by a derived class if it needs to decide on a number of menus. It returns the name of the menu to display. <p> <a name="menu"></a> <h3> Object::menu(MenuItem items[])</h3> This is invoked when the user has made a menu selection from a menu belonging to the object. If the program wishes to deal with menu hits, this function must be provided by a derived class. The function is passed an array of MenuItem structures which detail the selection made. It is up to the function to determine the action based on the selection. <p> <a name="help"></a> <h3> Object::help (int mx, int my, int buttons)</h3> This function is called when help is being requested. The default action is to return NULL, meaning that the object is not prepared to give anything away. Derived classes may provide their own help function. The function return a string (char *) which is a pointer to the help text. <p> The function is called when the mouse is over an object in the window. By returning NULL, you are asking the window to provide its own help. <p> <a name="x0"></a> <h3> Object::x0, Object::y0, Object::x1, Object::y1</h3> These are the bounding coordinates for the object. They are in window coordinates so (0,0) is at the top left and y is always negative. <p> <a name="window"></a> <h3>Object::window</h3> This is the window to which the object belongs. <p> <a name="default_menu"></a> <h3>Object::default_menu</h3> This is a pointer to the Menu which will be dislayed when the user clicks menu over the object. if it is NULL, there is no default menu. <p> <a name="next"></a> <h3>Object::next, Object::prev</h3> Pointers to the next and previous objects. The next object is guaranteed to be of the same or lower priority than this object. <p> <a name="name"></a> <h3>Object::name</h3> The name given to the object when it was created. <p> <a name="priority"></a> <h3>Object::priority</h3> The priority given to the object when it was created. It may be modified by writing to this class member. <p> <a name="selected"></a> <h3>Object::selected</h3> This contains the value 1 if the object is selected, 0 otherwise. An object is selected and unselected by use of the select() and unselect() functions. <h2>Predefined Objects</h2> Vista contains a set of predefined Objects for use by the program. These objects are meant to be used as example for defining you own objects, although they are fully functional. <p> The objects available are: <p> <a name="icon"></a> <h3>IconObject</h3> This object contains an <a href="file:icon">Icon</a> or one of its derived classes. <pre> class IconObject : public Object { public: IconObject (Window *w, char *name, Icon *icon, int priority = 0, char *menu = 0) ; ~IconObject() ; void redraw (int x0, int y0, int x1, int y1) ; private: Icon *icon ; } ; </pre> <p> <a name="rawsprite"></a> <h3>RawSpriteObject</h3> This object is a sprite. <pre> class RawSpriteObject : public Object { public: RawSpriteObject (Window *w, char *name, char *sprite, void *area, int x, int y, int priority = 0, char *menu = 0) ; RawSpriteObject (Window *w, char *name, char *sprite, int x, int y, int priority = 0, char *menu = 0) ; ~RawSpriteObject() ; void redraw (int x0, int y0, int x1, int y1) ; protected: char *sprite ; void *area ; int scale_factors[4] ; char *pixel_trans ; void init() ; int mode ; } ; </pre> <p> <a name="text"></a> <h3>TextObject</h3> This is an object which contains lines of text. The text can either be set when the object is created or can be added later. It will redraw itself when requested to by the Window and will only redraw the appropriate parts inside the clipping window. <pre> const int TextObject_Colour = 1 ; class TextObject : public Object { struct line { char *text ; // actual text int length ; // length in bytes } ; public: TextObject (Window *w, char *name, char *text, int x, int y, int priority = 0, char *menu = 0) ; TextObject (Window *w, char *name, int x, int y, int priority = 0, char *menu = 0) ; virtual ~TextObject() ; void redraw (int x0, int y0, int x1, int y1) ; void insert_line (char *text, int length) ; void insert_line (char *text) ; protected: char *text ; // text stored in object line *lines ; // array of lines int num_lines ; // number of lines int max_lines ; // mac line space available int max_length ; // max line length in units } ; </pre> <p> The text can contain line feeds and will be split into lines at these line feeds. The colour of the text can be set by inserting 2 byte sequence into the text. The first byte should be the value 1 and the second should be the colour to use. <p> The <a href="file:objects#font">FontObject</a> is a much superior object as it can display text in an outline font and has much more functionality. The TextObject should be used only when simple text is needed. <p> <a name="line"></a> <h3>LineObject</h3> This is an example of a graphics object. It draws a straight line. It does not do any clipping but relies on the OS to do it. <pre> class LineObject : public Object { public: LineObject (Window *w, char *name, int x1, int y1, int x2, int y2, int thickness = 1, int priority = 0) ; virtual ~LineObject() ; void redraw (int x0, int y0, int x1, int y1) ; protected: int thickness ; int dx ; // delta to add to x for thickness int dy ; // delta to subtract from y for thickness } ; </pre> The line's thinkness can be set. This is in OS units. <p> <a name="font"></a> <h3>FontObject</h3> This complex object displays text in an outline font. Once the object is created, you may add text to it and modify the appearance of the text until you tell it that you have finished. <p> The object exists at certain coordinates and has a certain width. The text in the object will be split at spaces inside the bounding box. <p> The object is created by passing a font handle to the constructor. This handle must be obtained by Task::open_font(). The add_text() function is used to add text to the end of any text already in the object. <p> When building the object, you may modify the appearance of the text as follows: <p> <ol> <li>Set the text colour to any RGB foreground and background colours. See the PRM for information about setting the text colour in a font. <li>Change the font. This allows things such as bold and italics to be used. <li>Underline a section of text. </ol> <p> The first line of the object may be indented from the left of the object by use of the 'set_indent()' functon. The indent is in OS units. <p> <a name="draw"></a> <h3>DrawObject</h3> This object renders a draw file on the screen. It relies on Acorn's DrawFile module which can be obtained from public domain libraries. The drawfile supplied to the constructor may be either a file on disk or held in memory. <pre> class DrawObject : public Object { public: DrawObject(Window *w, char *name, char *data, int length, int x, int y, int priority = 0, char *menu = 0) ; DrawObject(Window *w, char *name, char *filename, int x, int y, int priority = 0, char *menu = 0) ; DrawObject(Window *w, char *name, int priority = 0, char *menu = 0) ; ~DrawObject() ; void redraw (int x0, int y0, int x1, int y1) ; protected: char *data ; // draw data (in drawfile format) int data_length ; int matrix[6] ; // translation matrix int xoffset, yoffset ; // draw unit offset to bounding box bool dealloc_data ; // OK to deallocate data in destructor int max_length ; // max length for dynamic data array void init(int x, int y) ; // init for drawing on screen void make_header (int width, int height) ; // make a file header void insert_word (int word) ; // insert a word void insert_string (char *str) ; // insert a string void insert_byte (char c) ; // insert a byte void insert_data (void *s, int length) ; // insert a load of data void align() ; // align to next word void check_space (int num_bytes) ; // check space and extend if necessary } ; </pre> <p> <a name="sprite"></a> <h3>SpriteObject</h3> This is an alternative sprite object which uses the DrawObject. It copes with the various colour problems associated with sprites. <pre> class SpriteObject : public DrawObject { public: SpriteObject (Window *w, char *name, char *sprite, int x, int y, int priority = 0, char *menu = 0) ; ~SpriteObject() ; } ; </pre> You can derive other objects from the Object class at will. If you find that the predefined objects do not suit your purposes, you should define your own or derive a new object from the predefined ones.