Previous

Next

Class PegThing

PegThing is the base class from which all viewable objects are derived. While most applications never create an instance of a actual PegThing, you will be using the public functions of PegThing frequently.

PegThing objects are not viewport objects. If you are constructing a large container class, you may want to derive that class from PegWindow, rather than from class PegThing. For small custom gadgets, PegThing works well as a foundation upon which to build custom class.

In addition to the true member functions, PegThing implements several inline wrapper functions. These functions provide a simplified syntax for calling member functions of the PegScreen and PegMessageQueue classes. For example, you can always draw a line by calling the PegScreen Line function directly:

Screen()->Line(this, .....);

However, for the most common operations PegThing provides an inline wrapper function that eliminates the need to obtain the PegScreen instance pointer. This improves the API syntax and eliminates typing effort. The above function can more easily be invoked by using the wrapper function:

Line(...);

Wrapper functions have the same names and parameters as the original function except for the Caller parameter, which is missing. The following wrapper functions are available in class PegThing:

PegScreen::BeginDraw 
PegScreen::Bitmap 
PegScreen::BitmapFill 
PegScreen::CapturePointer 
PegScreen::Circle 
PegScreen::DrawText 
PegScreen::EndDraw 
PegScreen::Invalidate 
PegScreen::Line 
PegScreen::Rectange 
PegScreen::RectMove 
PegScreen::ReleasePointer 
PegScreen::SetPointerType 
PegScreen::TextHeight 
PegScreen::TextWidth 
PegMessageQueue::SetTimer 
PegMessageQueue::KillTimer 

class PegThing 
{ 
   public: 
      PegThing(const PegRect &Rect, PEGUINT wId = 0, PEGUINT wStyle = FF_NONE); 
      PegThing(PEGUINT wId = 0, PEGUINT wStyle = FF_NONE); 
      virtual PEGINT Message(const PegMessage &Mesg); 
      virtual void Draw(void); 
      virtual void Add(PegThing * Who, BOOL bDraw = TRUE); 
      virtual void AddToEnd(PegThing * Who, BOOL bDraw = TRUE); 
      virtual void MoveToFront(PegThing * Who, BOOL bDraw = TRUE); 
      virtual PegThing * Remove(PegThing * Who, BOOL bDraw = TRUE); 
      virtual void SetColor(const UCHAR uIndex, const COLORVAL uColor); 
      virtual COLORVAL GetColor(const UCHAR uIndex); 
      virtual void Center(PegThing * Who); 
      virtual void DrawChildren(void); 
      virtual void Resize(PegRect Rect); 
      void Destroy(PegThing * Who); 
      const PEGCHAR * Version(void); 

      PegThing * Parent(void); 
      PegThing * First(void); 
      PegThing * Next(void); 
      PegThing * Previous(void); 

      static PegPresentationManager * Presentation(void); 
      static PegMessageQueue * MessageQueue(void); 
      static PegScreen * Screen(void); 

      UCHAR Type(void); 
      void  Type(UCHAR uSet); 

      PEGUINT  Id(void); 
      void  Id(PEGUINT wId); 

      virtual PegThing * Find(PEGUINT wId, BOOL bRecursive = TRUE); 

      void SetSignals(PEGUINT wMask); 
      void SetSignals(PEGUINT wId, PEGUINT wMask); 
      PEGUINT GetSignals(void); 
      BOOL CheckSendSignal(UCHAR uSignal); 

      BOOL StatusIs(PEGUINT wMask); 
      virtual void AddStatus(PEGUINT wOrVal); 
      virtual void RemoveStatus(PEGUINT wAndVal); 
      PEGUINT GetStatus(void); 

      void FrameStyle(PEGUINT wStyle); 
      PEGUINT FrameStyle(void); 
      virtual PEGUINT Style(void); 
      virtual void Style(PEGUINT wStyle); 
      virtual void InitClient(void); 
      virtual PegPoint CenterOf(PegThing * Who); 

      virtual void SendSignal(UCHAR uSignal); 
      void StandardBorder(COLORVAL bFillColor); 

      void MessageChildren(const PegMessage &Mesg); 

      void UpdateChildClipping(void); 
      virtual void ParentShift(PEGINT x, PEGINT y); 
      Viewport * ViewportList(void); 

      virtual void DefaultKeyHandler(const PegMessage &Msg); 

      virtual BOOL CheckDirectionalMove(PEGINT iKey); 
      virtual PegThing * FindNearestNeighbor(PEGINT iKey, PegThing * pStart, PegPoint iCenter); 
      PegThing * FindNearestNeighbor(PegThing * pStart, LONG * pPutDist, PEGINT iKey, PegPoint CenterThis, BOOL bLoose); 
      LONG Distance(PegPoint p1, PegPoint p2); 


      PegThing * PrevTabLink(void); 
      PegThing * NextTabLink(void); 
      void SetTabOrder(PEGUINT * pIds); 
      void SetDefaultTabLinks(void); 
      void SetTabLink(PegThing * pNext); 

      COLORVAL muColors[4]; 
      PegRect mReal;       // outer limits of an object, inclusive 
      PegRect mClient;     // client area of a window or control 
      PegRect mClip;       // clipping rectangle of the object 
};

Signals

PSF_SIZED, PSF_FOCUS_RECEIVED, SF_FOCUS_LOST, PSF_KEY_RECEIVED, PSF_RIGHTCLICK.

Constructors

The first constructor is used when the desired initial position of the object on the screen is known at the time of object creation. Parameter Rect contains the starting screen coordinates for the object. The wStyle parameter indicates the object's initial drawing style.

The second constructor is used when the object position is not known at the time of object creation. When this is the case, it is necessary to define the object's position some time between when the object is created and when the object is drawn on the screen. This can be done in a derived class constructor, or when the object receives the PM_SHOW message.

The easiest way to set an object's position is to call the member function Resize(), which accepts a PegRect argument which should contain the desired screen coordinates. Calling Resize() is the only acceptable way to set an objects size or position after the object is visible.

A more direct method of setting an object's position and size is to directly modify the objects mReal (the absolute bounding rectangle of an object) and mClient (the inside client area of an object) variables. This method must be used with caution since PEG base classes often must insure that mClient remains correctly positioned relative to mReal. Also, you should never directly modify mReal or mClient after an object is visible, since this will usually not have the desired result due to PEG clipping enforcement.

Method Message

Message is called by PegPresentationManager to allow an object to process a message. The message handler should usually return 0. A non-zero value is used to terminate modal window execution. PegWindow derived classes such as PegDialog and PegMessageWindow return non-zero results when a signal from a child control is received that causes the window to close.

A complete list of all PEG system messages is contained in section struct PegMessage.

Method Draw

Draw is called by PegPresentationManager when an object needs to redraw itself, or by the application software when an object has been modified.

Method Add

Adds object Who to the current object. Parameter Who thus becomes a child of this. Add is used to make windows and controls members of the presentation tree.

An object is normally drawn after being added to a visible parent. This operation can be prevented, if desired, by passing a FALSE value as the bDraw parameter to the Add function.

If the object Who is already a member of the current object's child list, Who is not added again to the list, but instead Who is simply unlinked from the child list and re-linked at the head of the child list. This action changes the order of child objects, which may be the desired operation.

Objects are added to the parent according to the status of the object, meaning that objects with PSF_VIEWPORT status or PSF_ALWAYS_ON_TOP status are always maintained ahead of child objects which do not have this status. These differences are maintained internally by PEG and are necessary to insure proper drawing, but are not normally the concern of the application level program.

If Who is not visible at the time this function is called, and the object this is visible, a PM_SHOW message will be sent to Who to inform it that it has become visible. If the calling object is not visible at the time Who is added, and the calling object later becomes visible (by addition to a visible object), PM_SHOW messages will be sent at that time to the calling object and all of its children.

When constructing complex windows and dialogs, it is best to first add all of the child objects to the main window or dialog, and then add the main window or dialog to PegPresentationManager. This is slightly more efficient than adding each child object to a window or dialog that is already visible.

Method AddToEnd

AddToEnd adds parameter Who to the current object. Who thus becomes a child of this. AddToEnd works very much like Add(), except the added object is added to the end of the linked list of child objects, rather than being added to the head of the linked list. This is sometimes useful when adding objects to PegList containers, to correct the order of child display. Like the Add() function, AddToEnd() operates within the constraints of object status, meaning that objects with PSF_VIEWPORT status or PSF_ALWAYS_ON_TOP status are always maintained ahead of child objects which do not have this status.

Method MoveToFront

MoveToFront is used to change the z-order of a parent's child objects. This is useful when objects overlap in the parent's client area. In this case, one object may be brought to the front when selected, so that it is drawn on top of its siblings. The Add() function can also be used to move an object which is already a child to the front of the child list. However, this function differs from the Add() function in that MoveToFront does not change the sequential order of objects, i.e. the tab order is not modified by calling MoveToFront. The presentation tree is simply modified such that the caller is moved to be the first child object. Like the Add() function, MoveToFront() operates within the constraints of object status, meaning that objects with PSF_VIEWPORT status or PSF_ALWAYS_ON_TOP status are always maintained ahead of child objects which do not have this status.

Method Remove

Removes a child object from the current object's child list. Remove() is the opposite to Add(). Attempting to remove an object which is not in the child list has no effect. When an object is removed from a visible parent, it will receive a PM_HIDE message to notify it that it has been removed from the screen.

Remove() does not delete the object after is has been removed. In fact the purpose of Remove() is to allow you to remove objects from the screen without deleting them, allowing you to later re-display the object simply by re-adding it to a visible window. If you want to remove and delete an object, the PegThing member function Destroy() is provided for that purpose.

Method SetColor

SetColor is called to override an object's default color values. Every object has at least four color indexes, any of which can be reset using the SetColor function. The color indexes which can be passed in uIndex are defined as follows:

PCI_NORMAL

The normal client area fill color.

PCI_SELECTED

The fill color when the object is selected.

PCI_NTEXT

The normal text color for the object.

PCI_STEXT

The text color to use when the object is selected.

The available uColor values are defined in the file Pegtypes.hpp. These color values will vary depending on the color depth supported on the target system. A few objects such as PegTable have additional color values associated with them.

Method Center

Center will adjust the screen coordinates of Who such that Who is horizontally and vertically centered over the client area of this. Who does not necessarily have to be a child of this, although this is the most common case. The following example demonstrates centering an object on the screen:

PegRect Rect; 
Rect.Set(0, 0, 100, 100);               // create 100x100 pixel window 
PegWindow * MyWin = new PegWindow(Rect); 
Presentation()->Center(MyWin);          // center window on the screen 
Presentation()->Add(MyWin);             // make the window visible

Method DrawChildren

DrawChildren tells each child of the current object to draw itself by calling the individual child object draw functions. In your derived classes, you do not usually need to call this function since this is normally handled automatically when you call the base class drawing function. However, if you choose not to call the base class drawing function in your custom Draw() function, you will usually want to call DrawChildren() at some point in your drawing routine to insure that objects which have been added to your parent class draw themselves.

Method Resize

Any object can resize itself or any other object by calling the Resize() function. The new screen coordinates for the object are passed in the parameter Rect. If you maintain or find a pointer to another object, you can also resize that object by calling the same function. The following example illustrates this concept:

PegRect Rect(10, 10, 40, 40); 
PegButton * MyButton = new PegTextButton(Rect, 0, "Hello"); 
. 
.  // esize MyButton: 
. 
Rect.Set(20, 20, 60, 60); 
MyButton->Resize(Rect);

If an object is visible when it is resized, it will automatically perform the necessary invalidation and drawing. It is perfectly OK to resize an object that is not visible, in fact in many cases this is the best time to do it.

Method Destroy

Destroy is called to remove an object from view and delete the memory associated with that object. If the object has no parent, it has already been removed from view in which case Destroy() simply deletes the object. In the case that Who == this, Destroy() will post a message to PegPresentationManager to delete the calling object.

Method Version

Returns a pointer to the PEG library version string.

Method Parent

Returns a pointer to the parent object, or NULL if the object has no parent.

Method First

Returns a pointer to the first child object.

Method Next

Returns a pointer to the objects next sibling, or NULL if the current object is the end node of the current branch of the object tree.

Method SetTabOrder

This function will override the default tab order of the object's children. The parameter pIds should be an array of object IDs sorted in the desired TAB order, with the last entry set to 0. Please make sure that this function is called after the base object becomes visible, because it is there that the default tab order is installed.

Example:

PEGINT MyPegClass::Message(const PegMessage &Mesg) 
{ 
   PEGUINT wOrder[] = {MyID_1, MyID_2, MyID_3, 0}; // Terminate with 0 
   switch(Mesg.wType) 
   { 
      case PM_SHOW: 
         PegWindow::Message(Mesg); // This will set the default tab order. 
         SetTabOrder(wOrder);      // This will set user-defined tab order. 
         break; 
  } 
}

Method SetDefaultTabLinks

SetDefaultTabLinks is called automatically by PegWindow derived objects when they receive the PM_SHOW message. This establishes the initial order of tabbing through the list of child objects. This function is also called when objects that can receive keyboard focus are added to a visible window.

The default tab order is determined from the position of child objects with PSF_ACCEPTS_FOCUS status. Child objects are placed in the tab list in a top-to-bottom, left-to-right search order. By default, the child object which initially receives input focus is always the top most, left most child object. The application program can change the default initial focus by first finding the child object with PSF_DEFAULT_FOCUS status and removing this status by calling pChild->RemoveStatus(PSF_DEFAULT_FOCUS). The application can then redefine the initial focus by calling pChild->SetStatus(PSF_DEFAULT_FOCUS) on the desired child object.

Method SetTabLink

SetTabLink can be used to change the TAB successor of an object. parameter pNext specifies which object will receive the focus after this.

Method NextTabLink

Returns a pointer to the object which is next in the tab order, if known, otherwise NULL. RTPEG-32 objects which accept keyboard input focus are linked together in a circular list when the parent window is displayed. The order of this circular list is defined by the order in which child objects are added to the parent window.

Method PrevTabLink

Returns a pointer to the object which is previous in the tab order, if known, otherwise NULL. RTPEG-32 objects which accept keyboard input focus are linked together in a circular list when the parent window is displayed. The order of this circular list is defined by the order in which child objects are added to the parent window.

Method Presentation

Returns a pointer to the application's instance of PegPresentationManager.

Example:

PegWindow * MyWindow = new PegWindow(Rect); 
Presentation()->Add(MyWindow);

Method MessageQueue

Returns a pointer to the application's instance of PegMessageQueue.

Method Screen

Returns a pointer to the application's PegScreen object.

Method Type

Returns or sets the objects enumerated type.

Method Id

Assigns or queries the value of the object's mwId member. The default value is 0. Object Ids are used for signaling classes to determine the message number associated with notification messages. For all other class types, mwId has no effect, but can be useful to the application level software for identifying objects at run time.

Method Find

This method can be used to find any object based on the object ID value. The following example illustrates using Find() to locate a child PegString control and testing to see if the PegString has a non-NULL string value. If the string has a null value, the dialog OK button will not close the dialog. For this example, we assume the desired string has the enumerated ID value IDS_MY_STRING:

PEGINT MyDialog::Message(const PegMessage &Mesg) 
{ 
   switch (Mesg.wType) 
   { 
      case SIGNAL(IDB_OK, PSF_CLICKED): 
          PegString * pString = (PegString *) Find(IDS_MY_STRING); 
          if (pString->DataGet()) // Does string contain text? 
             return PegDialog::Message(Mesg); 
          break; 
   } 
   return 0; 
}

Method SetSignals

SetSignals is used to identify which notification messages a signaling control should send to its parent. The mask value should be created by using the SIGMASK macro. This enables multiple signals to be enabled with one call to SetSignals, similar to the object style flags. The available signal values are listed in section Signals.

Example:

SetSignals(SIMASK(PSF_CLICKED) | SIGMASK(PSF_RIGHTCLICK));

Method GetSignals

GetSignals returns a bitmap of signals current set for the object.

Method StatusIs

StatusIs is used to test individual bits of an objects private mwStatus variable. This variable contains system status flags common to all PegThing-derived classes. An application generally should never attempt to modify these flags, however it is sometimes useful to read this value to test for certain object states.

Method AddStatus

AddStatus can be used to modify an object's mwStatus flags. AddStatus will logically OR the wMask parameter with the object's mwStatus variable. This function is used often by the predefined objects to modify the state of visible window or control, but is rarely used by the application level software.

Method RemoveStatus

Clears individual bits or a combination of bits in an object's mwStatus variable.

Method GetStatus

returns all currently set status bits of the object.

Method FrameStyle

FrameStyle queries or modifies the appearance of the frame for most PegThing derived objects. This function is provided for convenience, and is is nearly identical to the Style() function shown below with the exception that it guarantees that only the objects frame style is modified, whereas the Style() function can modify all style flags.

Method Style

This function is used to query or set the style flags for an object. Not all style flags are supported by all classes. In all cases, the desired style flags can be ORed together to form one style parameter. All available style flags are listed in section Style Flags.

Method InitClient

InitClient should be called if the frame or border style of the object is modified at run time after the object has been initialized. This function determines the new client area rectangle based on the mReal rectangle and frame style. Many classes override this function to do a custom calculation.

Method CenterOf

CenterOf returns the center coordinates of the given object.

Method SendSignal

Creates and send a PegMessage with the appropriate SIGNAL value loaded in wType, object ID loaded in iData, this loaded in pSource, and Parent() loaded into the pTarget field of the message.

Method CheckSendSignal

Calls SendSignal if the specified signal has been enabled using SetSignals. The return value indicates whether the signal was sent.

Method StandardBorder

Draws a standard border based on the object frame style, fill color, and mReal values.

Method MessageChildren

This function passes the given message on to all of its children.

Method DefaultKeyHandler

DefaultKeyHandler is called by default when PM_KEY messages are received. This function checks for keys which cause an input focus change, such as TAB and ARROW keys. If the key is not one of these keys, the function checks if a PSF_KEY_RECEIVED signal must be sent to the parent. Finally, if none of these operations are performed, the key is passed up to the parent of the current object.

DefaultKeyHandler may be overridden in derived classes to perform custom key handling, although it is more common to simply catch PM_KEY messages in derived classes.

Method CheckDirectionalMove

Default arrow key handling. Returns TRUE if the key was processed, otherwise FALSE.

Method FindNearestNeighbor

This function is used for arrow key handling. It finds the nearest object in a specified direction.

Method Distance

This function calculates the distance between two PegPoints.

Class PegScreen

Class PegTextThing