Vaca::Widget Class Reference

#include <Widget.h>

Inheritance diagram for Vaca::Widget:

Vaca::Component Vaca::Referenceable Vaca::NonCopyable Vaca::ButtonBase Vaca::ComboBox Vaca::DataGrid Vaca::DockArea Vaca::DockBar Vaca::Edit Vaca::Frame Vaca::GroupBox Vaca::Label Vaca::ListBox Vaca::ListView Vaca::MdiClient Vaca::Panel Vaca::ProgressBar Vaca::ReBar Vaca::SciEditor Vaca::Separator Vaca::Slider Vaca::SpinButton Vaca::Spinner Vaca::StatusBar Vaca::TabBase Vaca::ToolSet Vaca::TreeView

List of all members.


Detailed Description

Base class for widgets.

What is a widget? Widgets are windows, buttons, text-fields, combo-boxes, etc. Each element in a window is a widget.

Win32 Specific:
This is a wrapper for HWND(W32). Calls CreateWindowEx(W32) and DestroyWindow(W32), and its wndProc method converts the messages ("WM_*") to events.

Public Types

typedef std::vector< Widget * > Container
 Collection of widgets.

Public Member Functions

 Widget (const WidgetClassName &className, Widget *parent, Style style=NoStyle)
 Creates a new widget with the specified class name.
virtual ~Widget ()
 Destroys the widget.
WidgetgetParent ()
 Returns the parent of the widget.
Container getChildren ()
 Returns the collection of children.
LayoutgetLayout ()
 Returns the current Layout that arranges the widget's children.
void setLayout (Layout *layout)
 Changes the current layout manager to arrange widget's children.
ConstraintgetConstraint ()
 Returns the widget's constraint.
void setConstraint (Constraint *constraint)
 Modifies the widget's constraint.
virtual void layout ()
 Must arranges the children bounds.
virtual bool isLayoutFree ()
 Returns true if the widget is layout-free, that means the Layout shouldn't arrange this widget.
virtual String getText ()
 Returns the widget's text, label, or frame's title.
virtual void setText (const String &str)
 Changes the widget's text, label, or frame's title.
virtual Font getFont () const
 Returns the current font used to paint the Widget.
virtual void setFont (Font font)
 Sets the font of the widget.
Style getStyle ()
 Returns the current Widget style.
void setStyle (Style style)
 Replaces all the styles of the Widget with the new ones specified in style parameter.
void addStyle (Style style)
 Adds styles to the widget.
void removeStyle (Style style)
 Removes styles from the widget.
Rect getBounds ()
 Gets the dimensions of the entire bounding rectangle that enclose the Widget.
Rect getAbsoluteBounds ()
 Gets the dimensions of the bounding rectangle relative to the upper-left corner of the screen (absolute position in the screen).
Rect getClientBounds ()
 Gets the client bounds.
Rect getAbsoluteClientBounds ()
 Gets the client bounds relative to the upper-left corner of the screen.
virtual Rect getLayoutBounds ()
 Returns the area where the Layout must arrange the collection of children.
void setBounds (const Rect &rc)
 Sets the boundary rectangle for the widget.
void setBounds (int x, int y, int w, int h)
void center ()
 Sets the bounds to the screen center.
void setOrigin (const Point &pt)
 Sets the origin position of the widget.
void setOrigin (int x, int y)
void setSize (const Size &sz)
 Sets the size of the widget.
void setSize (int w, int h)
Size getPreferredSize ()
 Returns the preferred size of the Widget.
Size getPreferredSize (const Size &fitIn)
 Returns the preferred size trying to fit in the specified size.
void setPreferredSize (const Size &fixedSize)
 Sets a fixed preferred size specified by the user.
void setPreferredSize (int fixedWidth, int fixedHeight)
bool isDoubleBuffered ()
 Returns true if the double-buffering technique is activated in this widget.
void setDoubleBuffered (bool doubleBuffered)
 Sets if you want or not to use a double-buffering technique to draw the entire widget content.
void validate ()
 Validates the entire widget.
void validate (const Rect &rc)
 Validates a part of the widget.
void invalidate (bool eraseBg)
 Invalidates the entire client area.
void invalidate (const Rect &rc, bool eraseBg)
 Invalidates the specified rectangle.
void update ()
 Flushes the widget invalidated area to redraw it now.
void updateIndicators ()
 Refreshes the state of indicators that could be inside this widget.
bool isVisible ()
 Returns true if this widget is visible.
virtual void setVisible (bool visible)
 Changes the visibility of this widget.
bool isEnabled ()
 Returns true if the widget is enabled.
void setEnabled (bool state)
 Changes the enable-state of the widget.
Color getFgColor ()
 Gets the foreground color.
Color getBgColor ()
 Gets the background color.
virtual void setFgColor (const Color &color)
 Sets the foreground color.
virtual void setBgColor (const Color &color)
 Sets the background color.
int getOpacity ()
 Returns the widget opacity.
void setOpacity (int opacity)
 Sets the alpha property of the widget.
void requestFocus ()
 Sets the keyboard focus to this Widget.
void releaseFocus ()
 Frees the keyboard focus.
void captureMouse ()
 Captures the mouse to receive its events even when it's outside the widget (you must call Widget::releaseCapture when you are done with the mouse).
void releaseMouse ()
 Releases the previously captured mouse (Widget::acquireCapture).
bool hasFocus ()
 Returns true if the widget has the focus.
bool hasMouse ()
 Returns true if the widget has the mouse.
bool hasMouseAbove ()
 Returns true if the widget has the mouse above (it doesn't matter if the widget has the capture status).
bool hasCapture ()
 Returns true if the widget has captured the mouse.
void setCursor (const Cursor &cursor)
 You should use this method only inside onSetCursor() event.
void bringToTop ()
 Sends this window to the top.
void sendToBack ()
 Sends this window to the bottom.
void moveAfter (Widget *brother)
void moveBefore (Widget *brother)
ScrollInfo getScrollInfo (Orientation orientation)
void setScrollInfo (Orientation orientation, const ScrollInfo &scrollInfo)
 Changes the scroll information about this Widget.
int getScrollPos (Orientation orientation)
void setScrollPos (Orientation orientation, int pos)
Point getScrollPoint ()
void setScrollPoint (const Point &pt)
void hideScrollBar (Orientation orientation)
CommandfindCommandById (CommandId id)
 Returns the command with the specified ID searching in all the CommandsClient that this widget can know: itself, the parent (some ancestor), and the Application instance.
HWND getHandle ()
 Returns the HWND of this Widget.
HWND getParentHandle ()
 Returns the HWND of the parent, or NULL if this widget doesn't have a parent.
virtual bool preTranslateMessage (Message &msg)
 This routine is called before to dispatch the message.
LRESULT sendMessage (UINT message, WPARAM wParam, LPARAM lParam)
 Sends a message to the widget.
void addChild (Widget *child, bool setParent)
 Adds a child to this widget.
void removeChild (Widget *child, bool setParent)
 Removes a child from this widget.

Static Public Member Functions

static WidgetfromHandle (HWND hwnd)
 Returns the Widget pointer from an internal field of the specified HWND.
static WNDPROC getGlobalWndProc ()
 Returns the global Vaca windows procedure that is used in the WNDCLASS.

Public Attributes

Signal1< void, const Size & > Resize
Signal1< void, MouseEvent & > MouseEnter
Signal0< void > MouseLeave
Signal1< void, MouseEvent & > MouseDown
Signal1< void, MouseEvent & > MouseUp
Signal1< void, MouseEvent & > DoubleClick
Signal1< void, MouseEvent & > MouseMove
Signal1< void, MouseEvent & > MouseWheel
Signal0< void > CancelMode
Signal1< void, KeyEvent & > KeyUp
Signal1< void, KeyEvent & > KeyDown
Signal1< void, Event & > GotFocus
Signal1< void, Event & > LostFocus
Signal1< void, DropFilesEvent & > DropFiles

Protected Member Functions

virtual void onPreferredSize (Size &sz)
 It should calculates the preferred size for this widget.
virtual void onPaint (Graphics &g)
 Called then the WM_PAINT event is received.
virtual void onResize (const Size &sz)
 Called when the user changes the size of the widget/frame.
virtual void onMouseEnter (MouseEvent &ev)
 The mouse enters in the Widget.
virtual void onMouseLeave ()
 The mouse leaves the Widget.
virtual void onMouseDown (MouseEvent &ev)
 The mouse is inside the Widget and the user press a mouse's button.
virtual void onMouseUp (MouseEvent &ev)
 The mouse is inside the Widget and the user release a mouse's button.
virtual void onDoubleClick (MouseEvent &ev)
 The user made double click over the widget.
virtual void onMouseMove (MouseEvent &ev)
 The mouse is moving inside the Widget's client area.
virtual void onMouseWheel (MouseEvent &ev)
 The mouse is inside the Widget and the user spin the mouse's wheel.
virtual void onCancelMode ()
 Event generated when the user press ESC in a drag-and-drop operation for example.
virtual void onSetCursor (WidgetHitTest hitTest)
 Set the mouse's cursor depending of its position.
virtual void onKeyDown (KeyEvent &ev)
 The user presses a key.
virtual void onKeyUp (KeyEvent &ev)
 The user releases a key.
virtual void onGotFocus (Event &ev)
virtual void onLostFocus (Event &ev)
virtual bool onCommand (CommandId id)
 Called when a command by ID is activated by the user, this can be a menu item or an accelerator.
virtual void onUpdateIndicators ()
 Event called to update the state of indicators.
virtual void onBeforePosChange ()
virtual void onAfterPosChange ()
virtual void onScroll (Orientation orientation, int code)
virtual void onDropFiles (DropFilesEvent &ev)
 When the user drops files to the widget this event is generated.
virtual void onRemoveChild (Widget *child)
virtual bool onReflectedCommand (int id, int code, LRESULT &lResult)
 This method can be used to handle command notifications (WM_COMMAND(W32)) reflected from the parent.
virtual bool onReflectedNotify (LPNMHDR lpnmhdr, LRESULT &lResult)
 This method can be used to handle notifications (WM_NOTIFY(W32)) reflected from the parent.
virtual bool onReflectedDrawItem (Graphics &g, LPDRAWITEMSTRUCT lpDrawItem)
 Fired when the parent widget received the WM_DRAWITEM(W32) message.
void create (const WidgetClassName &className, Widget *parent, Style style)
 It creates the handle to be used in the Widget.
void subClass ()
 Does the classic Win32's subclassing replacing GWLP_WNDPROC(W32).
LRESULT defWndProc (UINT message, WPARAM wParam, LPARAM lParam)
 Calls the default Win32's window procedure.
virtual bool wndProc (UINT message, WPARAM wParam, LPARAM lParam, LRESULT &lResult)
 The customized window procedure for this particular widget.
bool doPaint (Graphics &g)
 Paints the widgets calling the onPaint event.
void setDefWndProc (WNDPROC proc)
 Sets the default procedure to be called by defWndProc when a message isn't processed.
void setDestroyHWNDProc (void(*proc)(HWND))
 Sets the destroy-procedure associated with this widget.

Private Member Functions

virtual HWND createHandle (LPCTSTR className, Widget *parent, Style style)
 This method creates the HWND(W32) handler for the Widget.

Static Private Member Functions

static LRESULT CALLBACK globalWndProc (HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam)
 The global procedure for Win32 used in all registered WNDCLASSes.

Private Attributes

HWND m_handle
 The window handler to use with the Windows API.
Container m_children
 Sorted collection of children.
Widgetm_parent
 The parent widget.
Color m_fgColor
 Foreground color, generally borders and text color.
Color m_bgColor
 Background color of the widget.
Constraintm_constraint
 Constraint used by the layout manager that own the parent widget.
Layoutm_layout
 Layout manager of this widget used to arrange its children.
bool m_hasMouse: 1
 Flag to indicate if this widget has the mouse.
bool m_deleteAfterEvent: 1
 Flag to indicate if we must delete the widget after the current event/message is processed.
bool m_doubleBuffered: 1
 Use an automatic double-buffering technique to call the onPaint event.
Font m_font
 Current font of the Widget (used mainly to draw the text of the widget).
Sizem_preferredSize
 Manually set preferred size.
WPARAM m_wparam
LPARAM m_lparam
HBRUSH m_hbrush
WNDPROC m_baseWndProc
 Procedure of the original Win32's control (like BUTTON(W32) or EDIT(W32)).
WNDPROC m_defWndProc
 The default Win32's window procedure to be called if a message isn't used.
void(* m_destroyHWNDProc )(HWND hwnd)
 Used by MdiChild to send a WM_MDIDESTROY instead of calling Win32's DestroyWindow function.

Friends

class MakeWidgetRef
void delete_widget (Widget *widget)
 Safe way to delete a widget from memory.

Member Typedef Documentation

typedef std::vector<Widget*> Vaca::Widget::Container

Collection of widgets.

Used to handle the list of children of each widget.


Constructor & Destructor Documentation

Widget::Widget ( const WidgetClassName className,
Widget parent,
Style  style = NoStyle 
)

Creates a new widget with the specified class name.

You can specify WidgetClassName::None as className if you want to call create method by your self (see TN002: CreateWindow and DestroyWindow (Win32)).

You can't create widgets from a HWND, so you can't treat an existent HWND like a Widget.

Parameters:
className Must be a registered WNDCLASS for Windows.
parent It's a Widget (generally a Frame) that will act as the container parent of the new widget.
style You can specify the style to be used to create the widget. Generally Vaca handles the styles in this way: If the class is called Button, the default style is ButtonStyle. There exist another global styles that can be used for every widget like FocusableStyle or VisibleStyle, but the specific styles for a particular class, e.g. Edit, end with ...EditStyle, like ReadOnlyEditStyle.

Widget::~Widget (  )  [virtual]

Destroys the widget.

Warning:
If the widget contains children, they will be automatically deleted.
Win32 Specific:
It calls DestroyWindow(W32) function.

See also:
TN002: CreateWindow and DestroyWindow (Win32), setDestroyHWNDProc


Member Function Documentation

Widget * Widget::getParent (  ) 

Returns the parent of the widget.

Win32 Specific:
This method doesn't use the GetParent(W32). Widget has a m_parent member to hold its parent.

Widget::Container Widget::getChildren (  ) 

Returns the collection of children.

The returned list is a copy of the original, so you can do with it what you want, in other words, doesn't matter if you add or remove elements from them, the original list of children will not be modified.

Layout * Widget::getLayout (  ) 

Returns the current Layout that arranges the widget's children.

For most widgets, the Layout will be NULL. But for widgets like Frame you should use setLayout to change the Layout manager.

Warning:
You shouldn't delete the returned pointer.
See also:
setLayout, getConstraint, TN010: Auto-deleted objects, TN011: Layout Managers

void Widget::setLayout ( Layout layout  ) 

Changes the current layout manager to arrange widget's children.

The layout pointer'll be deleted automatically in the ~Widget destructor. If you change the layout manager, the old layout is automatically deleted too.

Example:

 {
   Layout* layout1 = new MyLayout();
   Layout* layout2 = new MyBetterLayout();
   ...
   {
     Frame frame(...);
     frame.setLayout(layout1);
     frame.setLayout(layout2); // here layout1 is deleted automatically
   }
   ...
   // here layout2 doesn't exist (was automatically deleted in the Frame destructor)
 }

Ilegal example:

 {
   MyLayout myLayout(...);
   Frame frame(...);
   frame.setLayout(&myLayout); // <- ilegal! the layout will be deleted two times!
   ...
 }

Warning:
As general rule: You must to use dynamic allocated Layouts with this routine. In other words, you shouldn't create instances of Layout allocated in the stack.
See also:
getLayout, setConstraint, TN010: Auto-deleted objects

Constraint * Widget::getConstraint (  ) 

Returns the widget's constraint.

This constraint is used by the parent widget's Layout to know how to lay the widget. For example, the AnchorLayout uses a Anchor constraint to know what side of a widget is anchored.

Warning:
You shouldn't delete the returned pointer.
See also:
setConstraint, getLayout, TN010: Auto-deleted objects

void Widget::setConstraint ( Constraint constraint  ) 

Modifies the widget's constraint.

The constraint pointer'll be deleted automatically by the ~Widget destructor. If you change the constraint, the old constraint will be deleted automatically (the same behavior as setLayout).

See also:
getConstraint, setLayout, TN010: Auto-deleted objects

void Widget::layout (  )  [virtual]

Must arranges the children bounds.

The default implementation calls the Layout::layout method of the Widget's layout manager (Widget::m_layout), but you can override this to obtain your own behavior (you can avoid to use Layout manager if you want).

This method is called from Widget::onResize by default, so when the Widget is shown for first time or it's resized, this method is called.

See also:
getLayout, setLayout, getLayoutBounds.

Reimplemented in Vaca::BandedDockArea, Vaca::BasicDockArea, Vaca::ComboBox, Vaca::DockArea, Vaca::Frame, and Vaca::Spinner.

bool Widget::isLayoutFree (  )  [virtual]

Returns true if the widget is layout-free, that means the Layout shouldn't arrange this widget.

The default implementation looks for the VisibleStyle (if it's hidden, it's free of layout).

See also:
getLayout, setLayout

Reimplemented in Vaca::DockArea, Vaca::Frame, and Vaca::StatusBar.

String Widget::getText (  )  [virtual]

Returns the widget's text, label, or frame's title.

Win32 Specific:
It uses GetWindowTextLength(W32) and GetWindowText(W32).

See also:
setText

Reimplemented in Vaca::SciEditor, and Vaca::TabPage.

void Widget::setText ( const String str  )  [virtual]

Changes the widget's text, label, or frame's title.

Win32 Specific:
It uses the SetWindowText(W32).

Reimplemented in Vaca::SciEditor, and Vaca::TabPage.

Font Widget::getFont (  )  const [virtual]

Returns the current font used to paint the Widget.

Reimplemented in Vaca::TabBase.

void Widget::setFont ( Font  font  )  [virtual]

Sets the font of the widget.

Reimplemented in Vaca::LinkLabel, Vaca::SciEditor, and Vaca::TabBase.

Style Widget::getStyle (  ) 

Returns the current Widget style.

void Widget::setStyle ( Style  style  ) 

Replaces all the styles of the Widget with the new ones specified in style parameter.

Win32 Specific:
It uses SetWindowLong(W32) to setup the GWL_STYLE(W32) and GWL_EXSTYLE(W32).

See also:
addStyle, removeStyle

void Widget::addStyle ( Style  style  ) 

Adds styles to the widget.

See also:
setStyle

void Widget::removeStyle ( Style  style  ) 

Removes styles from the widget.

See also:
setStyle

Rect Widget::getBounds (  ) 

Gets the dimensions of the entire bounding rectangle that enclose the Widget.

The bounds are relative to the upper-left corner of the widget's bounds, or absolute to the screen if this Widget hasn't parent.

See also:
getClientBounds, getAbsoluteBounds

Rect Widget::getAbsoluteBounds (  ) 

Gets the dimensions of the bounding rectangle relative to the upper-left corner of the screen (absolute position in the screen).

See also:
getAbsoluteClientBounds, getBounds

Rect Widget::getClientBounds (  ) 

Gets the client bounds.

It is the area which you should use to draw the widget content.

Win32 Specific:
It's like GetClientRect(W32).

See also:
getBounds, getAbsoluteClientBounds

Rect Widget::getAbsoluteClientBounds (  ) 

Gets the client bounds relative to the upper-left corner of the screen.

See also:
getAbsoluteBounds, getClientBounds

Rect Widget::getLayoutBounds (  )  [virtual]

Returns the area where the Layout must arrange the collection of children.

It's generally the client bounds, but other widgets (like Tab) could use a small area inside the widget.

See also:
getClientBounds

Reimplemented in Vaca::DockBar, Vaca::Frame, Vaca::GroupBox, and Vaca::TabBase.

void Widget::setBounds ( const Rect rc  ) 

Sets the boundary rectangle for the widget.

The rectangle must be in absolute coordinates for widgets without parent, and relative otherwise.

See also:
getBounds

void Widget::setBounds ( int  x,
int  y,
int  w,
int  h 
)

Todo:
docme

void Widget::center (  ) 

Sets the bounds to the screen center.

See also:
setOrigin, setBounds

void Widget::setOrigin ( const Point pt  ) 

Sets the origin position of the widget.

It doesn't affect the size.

See also:
setBounds, center

void Widget::setOrigin ( int  x,
int  y 
)

Todo:
docme

void Widget::setSize ( const Size sz  ) 

Sets the size of the widget.

It doesn't affect the origin position.

See also:
setSize(int,int)

void Widget::setSize ( int  w,
int  h 
)

Todo:
docme

Size Widget::getPreferredSize (  ) 

Returns the preferred size of the Widget.

It checks if the preferred size is static (it means when it was set through setPreferredSize before) or if it's dynamic (this is the default and is when the onPreferredSize is used to determined the preferred size).

In another words, if you don't use setPreferredSize to set a static preferred size for the widget then onPreferredSize will be used to calculate it.

See also:
setPreferredSize, onPreferredSize, getPreferredSize(const Size &)

Size Widget::getPreferredSize ( const Size fitIn  ) 

Returns the preferred size trying to fit in the specified size.

Remember that if you use setPreferredSize this routine will return the static size which you specified manually.

Parameters:
fitIn This can have both attributes (width and height) in zero, which means that it'll behave same as getPreferredSize(). If the width is great than zero the onPreferredSize will try to fit in that width (this is useful to fit Label or Edit controls in a specified width and calculate the height it could occupy).
See also:
getPreferredSize

void Widget::setPreferredSize ( const Size fixedSize  ) 

Sets a fixed preferred size specified by the user.

Widget::getPreferredSize() will return this value if it's setted.

void Widget::setPreferredSize ( int  fixedWidth,
int  fixedHeight 
)

bool Widget::isDoubleBuffered (  ) 

Returns true if the double-buffering technique is activated in this widget.

See also:
setDoubleBuffered

void Widget::setDoubleBuffered ( bool  doubleBuffered  ) 

Sets if you want or not to use a double-buffering technique to draw the entire widget content.

With double-buffering technique you can avoid flickering effect.

See also:
isDoubleBuffered

void Widget::validate (  ) 

Validates the entire widget.

It removes all paint messages from the message queue, because a validated widget is like a widget that doesn't need to be repainted.

See also:
invalidate

void Widget::validate ( const Rect rc  ) 

Validates a part of the widget.

This means that the specified rectangle doesn't need to be repainted.

See also:
invalidate(bool)

void Widget::invalidate ( bool  eraseBg  ) 

Invalidates the entire client area.

All the widget will be repainted through an onPaint event.

Parameters:
eraseBg true means that the background should be erased (with a WM_ERASEBKGND message).
See also:
validate, invalidate(const Rect&, bool), update

void Widget::invalidate ( const Rect rc,
bool  eraseBg 
)

Invalidates the specified rectangle.

When the next round of paint messages is processed by the operating system the specified area will be redrawn. This means that the area will not be repainted immediately (you should call update method to do this).

Parameters:
rc Area to repaint.
eraseBg true means that the background should be erased with the background color specified by getBgColor (with a WM_ERASEBKGND message for example).
See also:
invalidate(bool), update

void Widget::update (  ) 

Flushes the widget invalidated area to redraw it now.

This routine should be used if you want to show the changes of the widget immediately without to wait for the message queue to be processed.

Win32 Specific:
It's like UpdateWindow(W32).

void Widget::updateIndicators (  ) 

Refreshes the state of indicators that could be inside this widget.

An indicator is a MenuItem or a ToolButton which its state changes depending the current context of the Application. The current context gives to you different states for every Command, so we have to call Command::isEnabled for every visible indicator associated to a Command. This means that updateIndicators updates the state of visible ToolBar buttons and MenuItems in the MenuBar (MenuItems in the sub-menus are updated when they are shown).

bool Widget::isVisible (  ) 

Returns true if this widget is visible.

If this widget or some of its parents has the visibility state, this routine returns true.

See also:
Frame::setVisible

void Widget::setVisible ( bool  visible  )  [virtual]

Changes the visibility of this widget.

The children are hidden too.

Reimplemented in Vaca::DockBar, and Vaca::Frame.

bool Widget::isEnabled (  ) 

Returns true if the widget is enabled.

Win32 Specific:
It's like to ask if the widget hasn't the WS_DISABLED(W32) style. Really, this method calls the IsWindowEnabled(W32) function.

void Widget::setEnabled ( bool  state  ) 

Changes the enable-state of the widget.

Win32 Specific:
If state is true removes the WS_DISABLED(W32) style, if state is false adds the WS_DISABLED(W32) style. It's like to call the EnableWindow(W32).

Color Widget::getFgColor (  ) 

Gets the foreground color.

The foreground color generally is the font color to be used.

Returns:
The current foreground color for the widget.
See also:
setFgColor

Color Widget::getBgColor (  ) 

Gets the background color.

Returns:
The current background color for the widget.
See also:
setBgColor

void Widget::setFgColor ( const Color color  )  [virtual]

Sets the foreground color.

This color is used when WM_CTLCOLOR* messages are received. The default value is the System::getColor(COLOR_WINDOWTEXT).

See also:
getFgColor

void Widget::setBgColor ( const Color color  )  [virtual]

Sets the background color.

This color is used on WM_ERASEBKGND and WM_COLORCTL* messages. The default value is the System::getColor(COLOR_3DFACE).

See also:
getBgColor

Reimplemented in Vaca::ListView, Vaca::ProgressBar, and Vaca::TreeView.

int Widget::getOpacity (  ) 

Returns the widget opacity.

If the current OS doesn't support translucent windows, it will always be 255.

Returns:
A value from 0 (completelly transparent) to 255 (completelly opaque)

void Widget::setOpacity ( int  opacity  ) 

Sets the alpha property of the widget.

It uses the SetLayeredWindowAttributes, if it's available, if not, does nothing.

Parameters:
opacity A value from 0 (completelly transparent) to 255 (completelly opaque)

void Widget::requestFocus (  ) 

Sets the keyboard focus to this Widget.

void Widget::releaseFocus (  ) 

Frees the keyboard focus.

void Widget::captureMouse (  ) 

Captures the mouse to receive its events even when it's outside the widget (you must call Widget::releaseCapture when you are done with the mouse).

void Widget::releaseMouse (  ) 

Releases the previously captured mouse (Widget::acquireCapture).

bool Widget::hasFocus (  ) 

Returns true if the widget has the focus.

bool Widget::hasMouse (  ) 

Returns true if the widget has the mouse.

When you capture the mouse, you continue having the .

See also:
hasCapture, hasMouseAbove

bool Widget::hasMouseAbove (  ) 

Returns true if the widget has the mouse above (it doesn't matter if the widget has the capture status).

See also:
hasMouse

bool Widget::hasCapture (  ) 

Returns true if the widget has captured the mouse.

See also:
hasMouse

void Widget::setCursor ( const Cursor cursor  ) 

You should use this method only inside onSetCursor() event.

void Widget::bringToTop (  ) 

Sends this window to the top.

void Widget::sendToBack (  ) 

Sends this window to the bottom.

void Widget::moveAfter ( Widget brother  ) 

Todo:
docme

void Widget::moveBefore ( Widget brother  ) 

Todo:
docme

ScrollInfo Widget::getScrollInfo ( Orientation  orientation  ) 

Todo:
docme

void Widget::setScrollInfo ( Orientation  orientation,
const ScrollInfo scrollInfo 
)

Changes the scroll information about this Widget.

Parameters:
orientation What scroll bar use (Horizontal or Vertical)
scrollInfo New scroll information to be changed.

int Widget::getScrollPos ( Orientation  orientation  ) 

Todo:
docme

void Widget::setScrollPos ( Orientation  orientation,
int  pos 
)

Todo:
docme

Point Widget::getScrollPoint (  ) 

Todo:
docme

void Widget::setScrollPoint ( const Point pt  ) 

Todo:
docme

void Widget::hideScrollBar ( Orientation  orientation  ) 

Todo:
docme

Command * Widget::findCommandById ( CommandId  id  ) 

Returns the command with the specified ID searching in all the CommandsClient that this widget can know: itself, the parent (some ancestor), and the Application instance.

The command is searched in this instance if the Widget is a CommandsClient (a dynamic_cast is used for this), then it looks for the parent (using this same method), and finally in the Application instance (if the Application is a CommandsClient).

HWND Widget::getHandle (  ) 

Returns the HWND of this Widget.

This can't be NULL.

See also:
fromHandle, getParentHandle

HWND Widget::getParentHandle (  ) 

Returns the HWND of the parent, or NULL if this widget doesn't have a parent.

See also:
getHandle

Widget * Widget::fromHandle ( HWND  hwnd  )  [static]

Returns the Widget pointer from an internal field of the specified HWND.

This routine makes sense only when the HWND comes from a Vaca's Widget. In other words, you should use this only if you known that the HWND was created inside Vaca bounds.

Win32 Specific:
Old versions of Vaca uses the GWL_USERDATA field to get the Widget, now it uses a property called "VacaAtom" (through GetProp(W32) function).

See also:
getHandle

WNDPROC Widget::getGlobalWndProc (  )  [static]

Returns the global Vaca windows procedure that is used in the WNDCLASS.

See also:
globalWndProc, wndProc

bool Widget::preTranslateMessage ( Message msg  )  [virtual]

This routine is called before to dispatch the message.

Win32 Specific:
It's used by Dialog to call IsDialogMessage(W32) for example.

Returns:
True if the message was translated and sent, so the GUI thread doesn't need to dispatch it.

Reimplemented in Vaca::Dialog, Vaca::Frame, and Vaca::MdiClient.

LRESULT Widget::sendMessage ( UINT  message,
WPARAM  wParam,
LPARAM  lParam 
)

Sends a message to the widget.

Win32 Specific:
It uses the SendMessage(W32) routine to send a message to the wrapped HWND(W32).

void Widget::addChild ( Widget child,
bool  setParent 
)

Adds a child to this widget.

Parameters:
child The child to add inside the widget.
setParent If it's true the Win32's SetParent will be used.

For internal use only.

void Widget::removeChild ( Widget child,
bool  setParent 
)

Removes a child from this widget.

Parameters:
child The child that we want to remove from the parent.
setParent If it's true the Win32's SetParent will be used.

For internal use only.

void Widget::onPreferredSize ( Size sz  )  [protected, virtual]

It should calculates the preferred size for this widget.

Parameters:
sz It's for input and output. You should put the preferred size in this value, but also you should read the input value to know if you must to fit the widget in some size. The possible values for sz are:
  • sz = Size(0, 0) to calculate the preferred size without restrictions.
  • sz = Size(width, 0) to calculate the preferred size with restricted <= width.
  • sz = Size(0, height) to calculate the preferred size with restricted <= height.

Reimplemented in Vaca::BandedDockArea, Vaca::BasicDockArea, Vaca::ButtonBase, Vaca::ComboBox, Vaca::DockArea, Vaca::DockBar, Vaca::Edit, Vaca::Frame, Vaca::GroupBox, Vaca::Label, Vaca::LinkLabel, Vaca::ListBox, Vaca::ProgressBar, Vaca::Separator, Vaca::Slider, Vaca::SpinButton, Vaca::Spinner, Vaca::StatusBar, Vaca::TabBase, and Vaca::ToolSet.

void Widget::onPaint ( Graphics g  )  [protected, virtual]

Called then the WM_PAINT event is received.

The default implementation calls the Graphics::noPaint to know that this widget doesn't paint the surface. If you override this method, remember: (1) to draw inside the Widget::getClientBounds limits, and (2) don't call the base method onPaint().

Warning:
Don't try to override the onPaint of a system control (like Button, Edit, etc.). You must to use the CustomButton, CustomEdit, etc. to do that.
 class MyWidget : public Panel
 {
 public:
   ...
   virtual void onPaint(Graphics& g)
   {
     Rect rc = getClientBounds();
     g.drawEllipse(rc);
   }
 };

See also:
onReflectedDrawItem

Reimplemented in Vaca::BandedDockArea, Vaca::DockBar, and Vaca::LinkLabel.

void Widget::onResize ( const Size sz  )  [protected, virtual]

Called when the user changes the size of the widget/frame.

Win32 Specific:
This event is generated when a WM_SIZE(W32) message is received.

Reimplemented in Vaca::DockBar, Vaca::Frame, and Vaca::Label.

void Widget::onMouseEnter ( MouseEvent ev  )  [protected, virtual]

The mouse enters in the Widget.

Win32 Specific:
This event is generated when the first WM_MOUSEMOVE(W32) message is received.

Reimplemented in Vaca::LinkLabel.

void Widget::onMouseLeave (  )  [protected, virtual]

The mouse leaves the Widget.

Win32 Specific:
This event is generated when WM_MOUSELEAVE(W32) message is received.

Reimplemented in Vaca::LinkLabel.

void Widget::onMouseDown ( MouseEvent ev  )  [protected, virtual]

The mouse is inside the Widget and the user press a mouse's button.

Win32 Specific:
This event is generated when WM_LBUTTONDOWN(W32), WM_MBUTTONDOWN(W32), or WM_RBUTTONDOWN(W32) message is received.

Reimplemented in Vaca::DockBar, and Vaca::LinkLabel.

void Widget::onMouseUp ( MouseEvent ev  )  [protected, virtual]

The mouse is inside the Widget and the user release a mouse's button.

Win32 Specific:
This event is generated when WM_LBUTTONUP(W32), WM_MBUTTONUP(W32), or WM_RBUTTONUP(W32) message is received.

Reimplemented in Vaca::DockBar, and Vaca::TreeView.

void Widget::onDoubleClick ( MouseEvent ev  )  [protected, virtual]

The user made double click over the widget.

The default implementation calls onMouseDown, so it is like a single click (converts double-clicks to single-clicks).

Warning:
If you override this event, don't call the base implementation.
See also:
onMouseDown

Reimplemented in Vaca::DockBar.

void Widget::onMouseMove ( MouseEvent ev  )  [protected, virtual]

The mouse is moving inside the Widget's client area.

If you capture the mouse, you should use the System::getCursorPos function to get the cursor position when it's outside the widget's client area.

Reimplemented in Vaca::DockBar, Vaca::LinkLabel, and Vaca::TreeView.

void Widget::onMouseWheel ( MouseEvent ev  )  [protected, virtual]

The mouse is inside the Widget and the user spin the mouse's wheel.

Win32 Specific:
This event is generated when WM_MOUSEWHEEL(W32) message is received.

void Widget::onCancelMode (  )  [protected, virtual]

Event generated when the user press ESC in a drag-and-drop operation for example.

Win32 Specific:
This event is generated when WM_CANCELMODE(W32) message is received.

Reimplemented in Vaca::DockBar.

void Widget::onSetCursor ( WidgetHitTest  hitTest  )  [protected, virtual]

Set the mouse's cursor depending of its position.

If you override this method, you shouldn't call Widget::onSetCursor if you don't want the default behaviour.

Parameters:
hitTest Where the mouse is.

Reimplemented in Vaca::LinkLabel.

void Widget::onKeyDown ( KeyEvent ev  )  [protected, virtual]

The user presses a key.

Parameters:
ev Has the information about the key pressed.
Win32 Specific:
If KeyEvent::getKeyCode is not 0 the received message was WM_KEYDOWN(W32), otherwise KeyEvent::getCharCode is not 0 and the message was WM_CHAR(W32).

Reimplemented in Vaca::LinkLabel.

void Widget::onKeyUp ( KeyEvent ev  )  [protected, virtual]

The user releases a key.

Win32 Specific:
This event is generated when WM_KEYUP(W32) message is received.

void Widget::onGotFocus ( Event ev  )  [protected, virtual]

Todo:
docme

Reimplemented in Vaca::LinkLabel.

void Widget::onLostFocus ( Event ev  )  [protected, virtual]

Todo:
docme

Reimplemented in Vaca::LinkLabel.

bool Widget::onCommand ( CommandId  id  )  [protected, virtual]

Called when a command by ID is activated by the user, this can be a menu item or an accelerator.

Parameters:
commandId Identifier of the command that was activated.
Returns:
It should returns true if the commandId was used.
Win32 Specific:
Don't confuse with onReflectedCommand: onCommand is used to handle command notifications that come directly from accelarators or menus, not from Win32's controls. Notifications by Win32's controls are handled via onReflectedCommand, onReflectedNotify, or onReflectedDrawItem.

See also:
Command

Reimplemented in Vaca::Frame, and Vaca::ToolBar.

void Widget::onUpdateIndicators (  )  [protected, virtual]

Event called to update the state of indicators.

See also:
Widget::updateIndicators

Reimplemented in Vaca::Frame, Vaca::ToolSet, and Vaca::ToolBar.

void Widget::onBeforePosChange (  )  [protected, virtual]

Todo:
docme
Win32 Specific:
This event is generated when WM_WINDOWPOSCHANGING(W32) message is received.

void Widget::onAfterPosChange (  )  [protected, virtual]

Todo:
docme ()
Win32 Specific:
This event is generated when WM_WINDOWPOSCHANGED(W32) message is received.

void Widget::onScroll ( Orientation  orient,
int  code 
) [protected, virtual]

Todo:
docme

Reimplemented in Vaca::Slider.

void Widget::onDropFiles ( DropFilesEvent ev  )  [protected, virtual]

When the user drops files to the widget this event is generated.

void Widget::onRemoveChild ( Widget child  )  [protected, virtual]

Reimplemented in Vaca::Frame.

bool Widget::onReflectedCommand ( int  id,
int  code,
LRESULT &  lResult 
) [protected, virtual]

This method can be used to handle command notifications (WM_COMMAND(W32)) reflected from the parent.

Parameters:
id Identifier of the control or menu item.
code Notification code.
lResult Result to return by the wndProc method.
Win32 Specific:
Don't confuse with onCommand: onReflectedCommand is used to handle commands that this widget by self generated, were sent to the parent, and finally were reflected to this widget again by the parent.

Reimplemented in Vaca::ButtonBase, Vaca::ComboBox, Vaca::Edit, Vaca::ListBox, Vaca::RadioButton, and Vaca::ToolSet.

bool Widget::onReflectedNotify ( LPNMHDR  lpnmhdr,
LRESULT &  lResult 
) [protected, virtual]

This method can be used to handle notifications (WM_NOTIFY(W32)) reflected from the parent.

Parameters:
lpnmhdr Information about the notification message.
lResult Result to return by the wndProc method.
Returns:
False if it doesn't use the notification.

Reimplemented in Vaca::ListView, Vaca::SciEditor, Vaca::SpinButton, Vaca::TabBase, and Vaca::TreeView.

bool Widget::onReflectedDrawItem ( Graphics g,
LPDRAWITEMSTRUCT  lpDrawItem 
) [protected, virtual]

Fired when the parent widget received the WM_DRAWITEM(W32) message.

Parameters:
g Graphics context to draw the item (you can obtain the HDC from this argument).
lpDrawItem Instance of the Win32 structure DRAWITEMSTRUCT to get information about the item to draw.
See also:
onPaint

Reimplemented in Vaca::CustomButton, and Vaca::CustomLabel.

void Widget::create ( const WidgetClassName className,
Widget parent,
Style  style 
) [protected]

It creates the handle to be used in the Widget.

The only way to customize this routine is overloading the Widget::createHandle method, calling Widget::Widget with WidgetClassName::None as className, and finally calling Widget::create from the constructor of your own widget class (for example as MdiClient::MdiClient does).

This method "must be" called in one constructor (in Widget::Widget or in your own class if you used a WidgetClassName::None as className in Widget's constructor).

Exceptions:
CreateWidgetException If the handle couldn't be created through the createHandle method.
Win32 Specific:
The widget handle is the HWND(W32).

See also:
createHandle, TN002: CreateWindow and DestroyWindow (Win32), m_handle

void Widget::subClass (  )  [protected]

Does the classic Win32's subclassing replacing GWLP_WNDPROC(W32).

In the GWLP_WNDPROC(W32) property of all HWND(W32) is the WNDPROC(W32) procedure that is called each time a message is arrived/processed by the Win32's message-queue. So this method changes that procedure by globalWndProc to hook all messages that come from Windows.

See also:
getGlobalWndProc, wndProc, TN002: CreateWindow and DestroyWindow (Win32), m_baseWndProc

LRESULT Widget::defWndProc ( UINT  message,
WPARAM  wParam,
LPARAM  lParam 
) [protected]

Calls the default Win32's window procedure.

The default window procedure is m_baseWndProc if it is not NULL, or m_defWndProc otherwise. Even if m_defWndProc was changed with setDefWndProc but m_baseWndProc is not NULL, m_defWndProc is completelly ignored anyway.

For internal use only.

See also:
setDefWndProc, m_defWndProc, m_baseWndProc

bool Widget::wndProc ( UINT  message,
WPARAM  wParam,
LPARAM  lParam,
LRESULT &  lResult 
) [protected, virtual]

The customized window procedure for this particular widget.

Win32 Specific:
This is called from Widget::globalWndProc. It should returns true when the defWndProc doesn't need to be called.

This method is called to intercept any message after the creation of the widget, and before the destruction. To intercept messages outside that range (before creation, and after disposition), you should customize defWndProc().

This method mainly converts a message to a event:

For reflection, it does:

  • When WM_COMMAND is received, the onReflectedCommand() event of the child is called when it is a WM_COMMAND from a control, or the onCommand() event of this widget is called when the command come from a menu or an accelerator.
  • When WM_NOTIFY is received, the onReflectedNotify() event of the child is called.
  • When WM_DRAWITEM is received, the onReflectedDrawItem() event of the child is called.

How to extend widget::wndProc method?

 class MyWidget : public Widget {
   ...
 protected:
   virtual bool wndProc(UINT message, WPARAM wParam, LPARAM lParam, LRESULT& lResult)
   {
     if (Widget::wndProc(message, wParam, lParam, lResult))
       return true;

     // ...Your code here...

     return false;
   }
   ...
 }

Returns:
True if the message was used and lResult contains a valid value to be returned by globalWndProc.
See also:
globalWndProc, getGlobalWndProc, defWndProc

Reimplemented in Vaca::Dialog, Vaca::DockFrame, Vaca::Frame, Vaca::GroupBox, Vaca::MdiChild, Vaca::MdiFrame, Vaca::ToolSet, and Vaca::TreeView.

bool Widget::doPaint ( Graphics g  )  [protected]

Paints the widgets calling the onPaint event.

This method check the value of m_doubleBuffered to do the double-buffering technique (draw in a Graphics of a temporary Image, and then copy it's content to g).

Parameters:
g Where to draw.

For internal use only.

void Widget::setDefWndProc ( WNDPROC  proc  )  [protected]

Sets the default procedure to be called by defWndProc when a message isn't processed.

For internal use only.

See also:
defWndProc, m_defWndProc

void Widget::setDestroyHWNDProc ( void(*)(HWND)  proc  )  [protected]

Sets the destroy-procedure associated with this widget.

Win32 Specific:
Each widget has a procedure to be called when it's destroyed, it is the last procedure to be called in ~Widget() destructor. By default it is DestroyWindow(W32).

See also:
~Widget

HWND Widget::createHandle ( LPCTSTR  className,
Widget parent,
Style  style 
) [private, virtual]

This method creates the HWND(W32) handler for the Widget.

It is called inside Widget::create, so if you overload createHandle, you must to call the Widget's constructor with WidgetClassName::None as className, and then use Widget::create in your own class's constructor. An example is the MdiChild class, which overwrites the createHandle method, so it does something like the following code:

 MdiChild::MdiChild(const String& title,
                    MdiClient* parent,
                    Style style)
   // className=WidgetClassName::None so "create" isn't called
   : Frame(WidgetClassName::None, "", NULL, NoStyle)
 {
   ...
   // we call "create" manually here
   create("Vaca.MdiChild", parent, style);
 }
 
 // it's invoked from "create" from the MdiChild's constructor
 HWND MdiChild::createHandle(...) { ... }

See also:
create, TN002: CreateWindow and DestroyWindow (Win32)

Reimplemented in Vaca::FindTextDialog, and Vaca::MdiClient.

LRESULT CALLBACK Widget::globalWndProc ( HWND  hwnd,
UINT  message,
WPARAM  wParam,
LPARAM  lParam 
) [static, private]

The global procedure for Win32 used in all registered WNDCLASSes.

It's unique goal is to get the Widget pointer from HWND using fromHandle, and to call its wndProc method.


Friends And Related Function Documentation

friend class MakeWidgetRef [friend]

void delete_widget ( Widget widget  )  [friend]

Safe way to delete a widget from memory.

It deletes the specified widget if it isn't referenced, or defer its deletion for a secure point of deletion (e.g. when it's completelly unreferenced after an event is processed).

See also:
TN006: Deleting a Widget inside its event


Member Data Documentation

HWND Vaca::Widget::m_handle [private]

The window handler to use with the Windows API.

Sorted collection of children.

The parent widget.

This could be NULL if the Widget is a Frame or something like that.

Foreground color, generally borders and text color.

Background color of the widget.

Constraint used by the layout manager that own the parent widget.

Layout manager of this widget used to arrange its children.

bool Vaca::Widget::m_hasMouse [private]

Flag to indicate if this widget has the mouse.

Flag to indicate if we must delete the widget after the current event/message is processed.

Use an automatic double-buffering technique to call the onPaint event.

See also:
setDoubleBuffered, doPaint

Current font of the Widget (used mainly to draw the text of the widget).

See also:
setText, setFont

Manually set preferred size.

If it's equal to NULL (by default it is) the preferred size is automatically calculated, if not this size is returned by getPreferredSize.

See also:
setPreferredSize

WPARAM Vaca::Widget::m_wparam [private]

LPARAM Vaca::Widget::m_lparam [private]

HBRUSH Vaca::Widget::m_hbrush [private]

WNDPROC Vaca::Widget::m_baseWndProc [private]

Procedure of the original Win32's control (like BUTTON(W32) or EDIT(W32)).

It's set in subClass method.

WNDPROC Vaca::Widget::m_defWndProc [private]

The default Win32's window procedure to be called if a message isn't used.

By default it is Win32's DefWindowProc(W32), but you can change it using setDefWndProc to replace it with other procedure like Win32's DefFrameProc(W32).

See also:
setDefWndProc, defWndProc

void(* Vaca::Widget::m_destroyHWNDProc)(HWND hwnd) [private]

Used by MdiChild to send a WM_MDIDESTROY instead of calling Win32's DestroyWindow function.

See also:
onResize

See also:
onMouseEnter

See also:
onMouseLeave

See also:
onMouseDown

See also:
onMouseUp

See also:
onDoubleClick

See also:
onMouseMove

See also:
onMouseWheel

See also:
CancelMode

See also:
onKeyUp

See also:
onKeyDown

See also:
onGotFocus

See also:
onLostFocus

See also:
onDropFiles