Contents

What is fGUI ?

fGUI basics
The factory
Event model
Legal Issues
Things to do
History

Tree of classes
About

The classes

fApplication
fClassInfo
fColor
fGroup
fObject
fPoint

The flexible GUI: fObject

Derived from: public fClassInfo

Declared in: fGUI/fObject.h

Library: fGUI.so


Overview

fObject is the base class for all classes that draw something on screen in fGUI. It declares the methods that are used within the layout system and implements most of them to reasonable defaults. See fGroup for methods not included in fObject.

fObject cannot be instantiated because it contains a true virtual methods, drawObject(). It is meant as a base for derived classes

fGUI is based on fObjects. All gadgets that can be handled by the fGUI system have to inherit from fObject.

Principles:

In fGUI every graphical object is a gadget. At the moment you can only use gadgets that are provided by fGUI.

fGUI uses only one BView to render itself, an instance of fView. Therefore fGUI has to do its own layout. The following will try to introduce you to the principles that are used.

Every gadget in fGUI has 4 different sizes. This may seem a little bit much, but read on :)

  • MinimumSize: This is the absolute minimum size an object may have.
  • MaximumSize: This is the absolute maximum size an object may have.
  • PreferredSize: This is the size the object wants to have. This is the size the objects thinks it will look best in.
These sizes are for internal use by the layoutengine. What really matters to the user is the fourth (and last) size:
  • current size
This is the size the gadget actually uses to render itself.

Additionally each gadget has these attributes:

  • current position
    Each gadget has of course its own position, stated in the coordinate system of the view it draws in.

  • horizontal and vertical weight
    Each gadget has weights which determine how much space it will get relativ to all the other gadgets in the same group. Gadgets that have the same weight will get the same space (only if none of them has a minimum or maximum size set that collides with the size that results from the weight).
    A weight of 0 is a special case. This tells fGUI that the gadget should not be resized at all. It will always have its preferred size instead.

  • horizontal and vertical border
    This attribute determines the amount of space that is added to the objects size to make the layout look better.

  • View
    This is the view the gadget will draw into.

  • Parent
    Every gadget that is managed by a group has the group set as its parent. It may call updateIfNeeded() to force a relayout (for example after a font size change).


Message Format

The messages that are used in the event model of fGUI have to conform to some strict rules:

  • The what member of the message has to be FGUI_EVENT.

  • These are the message fields defined by fGUI
    Type Name Short description
    int32 fAction What action to perform by the target.
    int32 Event This is the event that caused the sending of the message.
    bigtime_t fTimeStamp Gives the time the message was sent. [from system_time()]
    fObject * fSourceObject A Pointer to the object that has sent the message.
    char * fSourceName The name of the object that has sent the message.
    fObject * fTargetObject The target of the message.
    char * fTargetName The target of the message. Can be an object, an instance of
    fWindow or an application signature.

Derived Classes

As already stated above any gadget that wants to participate in the layout must inherit from fObject. At least two methods have to be overridden by a derived class: drawObject() to actualle draw the class on screen and either recalculateSizeLimits() or all three of calculateMinimumSize(), calculatePreferredSize() and calculateMaximumSize() to set the correct size limits for the class.

If the object shall react to user input one or more of the mouseXXX-methods has to be reimplemented in the derived class.


Hook Functions

mouseDown() These methods are called when mouse buttons are pressed or released.
mouseUp()
mouseEntered() These methods are called when the mouse is moved within the object or over one of its boundaries.
mouseWithin()
mouseExited()
mouseMoved() This method is called everytime the mouse is moved, even outside the object. Use this with great care ! Objects using this method should only do very small things in here.
calculateMinimumSize() These methods have to be overridden by derived classes to calculate the size limits of that specific class.
calculatePreferredSize()
calculateMaximumSize()
recalculateSizeLimits()
setFont() setFont() is called every time the font settings change, either system-wide or just for the gadget on which it is called.
drawObject() drawObject() is called whenever fGUI thinks the gadget should be refreshed. That can be because the view was hidden or because new gadgets were added to the system.


Constructor and Destructor


fObject()

	fObject( void)
	fObject( const char *ObjectName)
Initializes the fObject to reasonible default values:
horizontal weight 100.0
vertical weight 100.0
horizontal border 1.0
vertical Border 1.0
minimum size fPoint( 2 * horizontal border, 2 * vertical border)
preferred size fPoint( 2 * horizontal border, 2 * vertical border)
maximum size fPoint( 2 * horizontal border, 2 * vertical border)


~fObject()

	virtual ~fObject( void)
Deletes the fObject and frees all resources that where allocated in the constructor.


Protected Functions


setMinimumSize(), setPreferredSize(), setMaximumSize()

    virtual void setMinimumSize( fPoint &Size)
    virtual void setPreferredSize( fPoint &Size)
    virtual void setMaximumSize( fPoint &Size)
Sets the minimum, preferred or maximum size of the gadget, respectively. This method adds the current horizontal and vertical borders correctly so you don't have to worry about them.


calculateMinimumSize(), calculatePreferredSize(), calculateMaximumSize()

    virtual void calculateMinimumSize( void)
    virtual void calculatePreferredSize( void)
    virtual void calculateMaximumSize( void)
In fObject these methods call the corresponding setXXXSize() method with a size of fPoint( 0.0, 0.0).

In derived classes these emthods should be overridden when the calculation of the size limits differs from each other. If it is possible to determine all size limits in one calculation ist better to override recalculateSizeLimits().


recalculateSizeLimits()

    virtual void recalculateSizeLimits( void)
recalculateSizeLimits is a shortcut for:

calculateMinimumSize();
calculatePreferredSize();
calculateMaximumSize();
For classes that have similar ways of calculating the size limits its better to override this method and set all size limits from here.


setClippingRegion()

    void setClippingRegion( const BRegion &ClippingRegion)
This method sets the cliping region the object has to use when drawing outside of the regular drawObject() calls. This is for example used in redraw().


removeEventRoutes()

    void removeEventRoutes( int32 fEvent)
This method removes all event reouytes from the internal list that match the given Event.


redraw()

    void redraw( BRect RedrawRectangle) const
redraw() calls drawObject() with a region according to the rectangle given. Call this method when you have drawing to do outside the normal call to drawObject().


Member Functions


setWeights(), setHorizontalWeight(), setVerticalWeight(), getHorizontalWeight(), getVerticalWeight()

	virtual void setWeights( float Weight)
	virtual void setHorizontalWeight( float Weight)
	virtual void setVerticalWeight( float Weight)

	float getHorizontalWeight( void) const
	float getVerticalWeight( void) const
setHorizontalWeight() and setVerticalWeight() set the horizontal and vertical weight of the object, respectively. setWeights() is a shortcut to set both weights to the same value.

getHorizontalWeight() and getVerticalWeight() return the current weight.

The weight of an object is the basis of all layouting activity. All objects with the same weight can expect to get the same space, except when that size would collide with the size limits of that object. A special case is a weight of 0.0. Such a weight tells the parent group to resize the object to its preferred size and not to calculate its size.


getMinimumSize(), getMaximumSize(), getPreferredSize()

	void getMinimumSize( fPoint &Size) const
	fPoint getMinimumSize( void) const

	void getMaximumSize( fPoint &Size) const
	fPoint getMaximumSize( void) const

	void getPreferredSize( fPoint &Size) const
	fPoint getPreferredSize( void) const
These methods return the size limits or modify given point according to the size limits. They are used by groups to determine wether a certain size is allowed for an object.


setSize(), getSize()

	virtual void setSize( const fPoint &NewSize)

	virtual void getSize( fPoint &Size) const
	fPoint getSize( void) const
setSize() sets the size of the object to NewSize. getSize() either returns the current size or it modifies Size so that it is equal to the current size.


setPosition(), getPosition()

	virtual void setPosition( const fPoint &NewPosition)

	void getPosition( fPoint &Position) const
	fPoint getPosition( void) const
setPosition() sets the position of the object to NewPosition, the position is given in the coordinate system of the BView in which the object will draw. getPosition() either returns the current position or it modifies Position so that it is equal to the current position.


getObjectFrame()

	void getObjectFrame( BRect &Position) const
	BRect getObjectFrame( void) const
getObjectFrame() returns the rectangle the object occupies. This rectangle is calculated from the current position and the current size.

If a rectangle is given it is modified to the size and position of the objects frame.

This method is used by drawObject() and containsPoint().


setBorders(), setHorizontalBorder(), setVerticalBorder(), getHorizontalBorder(), getVerticalBorder()

	virtual void setBorders( float NewBorder)

	virtual void setHorizontalBorder( float NewHorizontalBorder)
	virtual void setVerticalBorder( float NewVerticalBorder)

	float getHorizontalBorder( void) const
	float getVerticalBorder( void) const
setHorizontalBorder() and setVerticalBorder() set the horizontal and vertical border of the object, respectively. setBorders() is a shortcut to set both borders to the same value.

getHorizontalBorder() and getVerticalBorder() return the current border value.

The border of an object determines the space that the objects frame is inset in both horizontal and vertical direction before drawing. This increases the distances of the objects and makes the interface less crowded.


setHorizontalAlignment(), setVerticalAlignment(), getHorizontalAlignment(), getVerticalAlignment()

	virtual void setHorizontalAlignment( HorizontalAlignment NewAlignment)
	virtual void setVerticalAlignment( VerticalAlignment NewAlignment)

	HorizontalAlignment getHorizontalAlignment( void) const
	VerticalAlignment getVerticalAlignment( void) const
these method set and get the alignment of the object. Possible values are F_HALIGN_RIGHT, F_HALIGN_CENTER and F_HALIGN_LEFT for the horizontal alignment and F_VALIGN_TOP, F_VALIGN_CENTER and F_VALIGN_BOTTOM for the vertical alignment.

Alignment is used in two ways: First the group which contains the object acts upon the alignment values and secondly the object itself, if it has something to align can use these values.


setEnabled(), getEnabled()

	virtual void setEnabled( bool Enabled)

	bool getEnabled( void) const
setEnabled() enables or disables the object according to the value Enabled. Disabled objects should not except user input.This method is not normally called from outside the object but from within a href="#dispatchMessage()">dispatchMessage() in response to F_ENABLE_OBJECT and F_DISABLE_OBJECT events.

getEnabled() returns true if the ibject is enabled and false otherwise.


setFont()

	virtual void setFont( const BFont *Font)
This method sets the font the object should use when drawing. This method is empty in fObject.


setFontColor(), getFontColor()

	virtual void setFontColor( const fColor &FontColor)
	virtual void setFontColor( uint8 Red, uint8 Green, uint8 Blue, uint8 Alpha = 255)

	fColor getFontColor( void) const
Sets the color the object uses when drawing text. This method excepts either fColors or RGBA values.

getFontColor() returns the color used to draw text as a fColor.


setBackgroundColor(), getBackgroundColor()

	virtual void setBackgroundColor( const fColor &BackgroundColor)
	virtual void setBackgroundColor( uint8 Red, uint8 Green, uint8 Blue, uint8 Alpha = 255)
	fColor getBackgroundColor( void) const
Sets the color the object uses when drawing its background. This method excepts either fColors or RGBA values.

getFontColor() returns the color used to draw the background.


setBackgroundBitmap()

	virtual void setBackgroundBitmap( BBitmap *BackgroundBitmap)
This method is to set the background bitmap the object should use to clear its frame rectangle. This is currently not implemented, the method is empty.


containsPoint()

	virtual const fObject *containsPoint( const fPoint &Point) const
This method checks if the point Point falls within the objects frame rectangle, insetted by the horizontal and vertical border. This method is used by the objects parent group find the object for example a mouse button was pressed in.

Another use is in derived classes where in mouseUp() is checked if the mouse went up within the frame of the object.


mouseDown()

	virtual void mouseDown( MouseButton Button, const fPoint &Point, int32 Clicks)
Implemented by derived classes to react to the user pressing a mouse button. Point is the location of the click given in the coordinate system of the objects view. Button can currently have one of four values:
  • F_NO_MOUSE_BUTTON (shouldn't really happen...)
  • F_PRIMARY_MOUSE_BUTTON
  • F_SECONDARY_MOUSE_BUTTON
  • F_TERTIARY_MOUSE_BUTTON
When this method is called the object can be sure that Point lies within its frame rectangle.

The Clicks variable is one if that click is a solitary event and greater than one if it is part of a multiple click.


mouseUp()

	virtual void mouseUp( MouseButton Button, const fPoint &Point, int32 Clicks)
Implemented by derived classes to react to the user releasing a mouse button. Point is the location of the click given in the coordinate system of the objects view. Button can currently have four values, seel above.

Note:mouseUp() differs from mouseDown() in a very important point. mouseDown() is only called when the object contains the point given, therefore only once. But mouseUp() is called at least once but in some cases twice ! It is called for the object the mouse was over when the mouse button was released and it is called for the object in which the mouse button went down before !

The Clicks variable is one if that click is a solitary event and greater than one if it is part of a multiple click.


mouseEntered()

	virtual void mouseEntered( const fPoint &Point)
This method is called whenever the mouse enters the objects frame rectangle. Point is the current location of the cursor.


mouseWithin()

	virtual void mouseWithin( const fPoint &Point)
This method is called whenever the mouse is moved within the objects frame rectangle. Point is the current location of the cursor.


mouseExited()

	virtual void mouseExited( const fPoint &Point)
This method is called whenever the mouse has left the objects frame rectangle. Point is the current location of the cursor.


mouseMoved()

	virtual void mouseMoved( const fPoint &Point)
This method is called whenever the mouse moves. Point is the current location of the cursor.

Note:Because this method is called very often derived classes which implement it whould only do very fast things, otherwise the system will not keep up with the user moving the mouse.


setFocus(), getFocus()

	virtual bool setFocus( bool Focus)
	bool getFocus( void) const
setFocus() gives the focus to the object if Focus is true and loses it when it is false. This method is not normally called from outside the object but from within a href="#dispatchMessage()">dispatchMessage() in response to F_GOT_FOCUS and F_LOST_FOCUS events.

getFocus() return true if the object has the focus and false otherwise.


keyDown(), keyUp()

	virtual void keyDown( const char *Input, int32 Length)
	virtual void keyUp( const char *Input, int32 Length)
Implemented by derived classes these functions are called when the object has the focus and the user types on the keyboard. Input iss a pointer to an UTF-8 string of Length bytes Length. That is not necessarily equal to the number of characters in the Input !

Note that for example Alt-X, Alt-C and Alt-V are translated to events ( F_CUT, F_COPY and F_PASTE) and that if a default button is set the return key will not show up in the focussed object.


addEventRoute()

	virtual void addEventRoute( class fEventRoute *EventRoute)
This method adds the event route EventRoute to the objects list of event routes. It is used both internally by derived classes like fScrollBar to set up communication with child objects and externally by the programmer to set up routes between objects.


processEvent()

	virtual void processEvent( int32 Event, BMessage *Message = NULL)
This method is called by the objects parent window to dispatch events to the object. It is also used by the objects itself to react to user input. For example the fButton class calls processEvent( F_BUTTON_CLICKED); when the user operates the button.

processEvent() look through the list of event routes and when a route has the same event value as the event to process the event route is activated.


dispatchMessage()

	virtual void dispatchMessage( int32 Event, BMessage *Message)
After the event routes are processed the event is dispatched to the virtual methods after the needed arguments have been extracted from the message.

Note:Message can be NULL!


messageReceived()

	virtual void messageReceived( int32 Event, BMessage *Message)
When no virtual method for the event Event has been found the event is finally dispatched to messageReceived.

Note:Message can be NULL!


getCurrentMessage()

	const BMessage *getCurrentMessage( void) const
Returns a pointer to the message that is currently processed. This method will only return a useful value if it is called from within processEvent or a method called frmo there.


setName(), getName()

	virtual void setName( const char *Name)
	const char *getName( void) const
SetName() sets the name of the object to Name. The name of an object is used when an event has to be delivered and when the object itself sends an event to some other object.

getName() returns a pointer to the name of the object or NULL if no name was set.


setView(), getView()

	virtual void setView( BView *NewView)
	BView *getView( void) const
setView() sets the view in which the object shall draw itself. NewView may be NULL.

getView returns the view or NULL if none is set.


setParent(), getParent()

	virtual void setParent( fObject *Parent)
	fObject *getParent( void) const
setParent() sets the parent object for the object.

getParent returns the parent object or NULL if the object is not assigned to a group.


attachedToWindow(), detachedFromWindow()

	virtual void attachedToWindow( const class fWindow *ParentWindow)
	virtual void detachedFromWindow( void)
attachedToWindow() is called when the fView object the object belongs to is attached to the window ParentWindow. Derived classes can use this call to make final preparations prior to being drawn and the target of users actions. This call is for example used to set up event routes to the window.

detachedFromWindow() is called when the object is removed from the hierarchy or when the fView object the object belongs to is removed from the window.


getWindow()

	const class fWindow *getWindow( void) const
This method returns a pointer to the objects parent window.


setWindowActivated(), getWindowActivated()

	virtual bool setWindowActivated( bool Activated)
	bool getWindowActivated( void) const
setWindowActivated() is called with Activated true if the window the object is in has been activated and with false when it losesd that status.

getWindowActivated() returns true if the window the object is in is currently the activ window and false otherwise.


updateIfNeeded()

	virtual void updateIfNeeded( void)
This method is called by the object whenever its state changes and it feels that the system should make a re-layout of the display.Calls to updateIfNeeded() are for example made in setFont() and setWeights()


findObject()

	virtual bool findObject( const fObject *ObjectPointer) const
	virtual const fObject *findObject( const char *ObjectName) const
Allows the group to search for an object either by name or by its address. These methods are used to find the target of an event.


drawObject()

	virtual void drawObject( const BRegion &ClippingRegion, bool FullUpdate) const = 0
Implemented by derived classes to actually draw the object on screen. This method has no default implementation to make sure that no instance of this class can be created. FullUpdate is set to true by the objects parent if the call to drawObject() is part of a full update of the window. This can be caused by the window having been hidden and now being shown on screen or by changes in the windows size.


The flexible GUI, in HTML for the BeOS Release 3.

Copyright © 1997-1998 Stegemann & Co. All rights reserved.

Last modified May 19, 1998.