Difference between revisions of "Reference: MSEgui/TWidget"

From Free Pascal wiki
Jump to navigationJump to search
Line 148: Line 148:
  
  
====OptionsWidget and OptionsWidget1====
+
====OptionsWidget====
  
 
<syntaxhighlight>
 
<syntaxhighlight>
Line 167: Line 167:
 
optionswidgetty = set of optionwidgetty;
 
optionswidgetty = set of optionwidgetty;
  
 +
property OptionsWidget: optionswidgetty;
 +
</syntaxhighlight>
 +
 +
* If ow_mousefocus is set, the widget can get the focus by clicking on it.
 +
* If ow_tabfocus is set, the widget can get the focus using the tab key. See also TabOrder.
 +
* If ow_arrowfocus is set, the widget can get the mouse focus using the arrow keys.
 +
 +
 +
 +
====OptionsWidget1====
 +
 +
<syntaxhighlight>
 
optionwidget1ty = (ow1_fontglyphheight, //track font.glyphheight, create fonthighdelta and childscaled events
 
optionwidget1ty = (ow1_fontglyphheight, //track font.glyphheight, create fonthighdelta and childscaled events
 
   ow1_fontlineheight, //track font.linespacing, create fonthighdelta and childscaled events
 
   ow1_fontlineheight, //track font.linespacing, create fonthighdelta and childscaled events
Line 180: Line 192:
 
optionswidget1ty = set of optionwidget1ty;
 
optionswidget1ty = set of optionwidget1ty;
  
property OptionsWidget: optionswidgetty;
 
 
property OptionsWidget1: optionswidget1ty;
 
property OptionsWidget1: optionswidget1ty;
 
</syntaxhighlight>
 
</syntaxhighlight>
 
 
 
 
 
  
 
====PopupMenu====
 
====PopupMenu====

Revision as of 07:56, 3 February 2016

TWiget

work in progress

Ancestor for visual components.

Reference

Hierarchy

  • TObject
  • TPersistent
  • TComponent
  • TMseComponent
  • TActComponent
  • TWidget

Properties

Anchors

Anchors combines the traditional Anchors and the traditions Align properties.

msegui anchors.png

property anchors: anchorsty read fanchors write setanchors default defaultanchors;

By default your anchors are an_left and an_top. Then your widget stays at the same position when sizing the form. When your widget should have a constant distance to the right border of its parent, you add an_right and remove an_left (in this order...). The same you can do with an_bottom and an_top.

If you have only one anchor, and the widget is suitable for this sizing, the widget is using the full size of the not anchored dimension. The behaviour is near the traditional property Align, but the widget is not aligned directly to the border, but you can free position it.

msegui an top.png

By having no anchors set, the widget fills the client size of its parent (the traditional alClient).

By setting an_left and an_top, the widget change its horizontal size by sizing its parent, the same with the vertical size by setting an_top and an_bottom together.

Bounds

The size and the position of the widget is condensed in the property bounds, but you have also the traditional properties like left an width.

msegui bounds.png

// the types
sizety = record
  cx, cy: integer;
end;

pointty = record
  x,y: integer;
end;

rectty = record
case integer of
  0: (x, y, cx, cy: integer);
  1: (pos: pointty; size: sizety);
end;


// the properties
property Widgetrect: rectty read FWidgetrect write SetWidgetrect;
property Pos: pointty read FWidgetrect.pos write SetPos;
property Size: sizety read FWidgetrect.size write SetSize;

property Bounds_x: integer read FWidgetrect.x write SetBounds_x;
property Bounds_y: integer read FWidgetrect.y write SetBounds_y;
property Bounds_cx: integer read FWidgetrect.cx write SetBounds_cx
               {default defaultwidgetwidth} stored true;
property Bounds_cy: integer read FWidgetrect.cy write SetBounds_cy
               {default defaultwidgetheight} stored true;
property Bounds_cxmin: integer read FMinSize.cx
                                   write SetBounds_cxmin default 0;
property Bounds_cymin: integer read FMinSize.cy
                                   write SetBounds_cymin default 0;
property Bounds_cxmax: integer read FMaxSize.cx
                                   write SetBounds_cxmax default 0;
property Bounds_cymax: integer read FMaxSize.cy
                                   write SetBounds_cymax default 0;

property Left: integer read FWidgetrect.x write SetBounds_x;
property Right: integer read GetRight write SetRight;
             //widgetrect.x + widgetrect.cx, sets cx if an_left is set
property Top: integer read FWidgetrect.y write SetBounds_y;
property Bottom: integer read GetBottom write SetBottom;
             //widgetrect.y + widgetrect.cy, sets cy if an_top is set
property Width: integer read FWidgetrect.cx write SetBounds_cx;
property Height: integer read FWidgetrect.cy write SetBounds_cy;

property MinSize: sizety read FMinSize write SetMinSize;
function WidgetMinSize: sizety;
        //calls checkwidgetsize and frame.checkwidgetsize
property MaxSize: sizety read FMaxSize write SetMaxSize;

Color

property Color: colorty default defaultwidgetcolor;

Specifies the color of the widget. With Face and Frame other colors for the whole or a part of the widget can set.

Cursor

property Cursor: cursorshapety default cr_default;

Specifies the look of the mouse cursor if it is over the widget.

Enabled

property Enabled: boolean default true;

Sets the widget enabled or not. Some Widgets change their look if they are not enabled, others do not (UPDATE: Meanwhile TSlider change it's look when setting enabled).

msegui enabled.png

Face

See TFace


Font

See TFont

Frame

See TFrame

Hint

A hint is a small text displayed when the mouse cursor is over the widget. With the text editor of the object inspector you can add additional lines (SHIFT+ENTER), you can also use [r[n:

Label1.Hint := 'This is a simple hin text[r[nof a simple label[r[nwith more than on line.'

msegui widget hint.png

See also OnHint


OptionsWidget

optionwidgetty = (ow_background, ow_top, ow_ultratop,
  ow_noautosizing, //don't use, moved to optionswidget1
  ow_mousefocus, ow_tabfocus, ow_parenttabfocus, ow_arrowfocus,
  ow_arrowfocusin,ow_arrowfocusout,
  ow_subfocus, //reflects focus to children
  ow_focusbackonesc,                   
  ow_keyreturntaborder, //key_return and key_enter work like key_tab
  ow_nochildshortcut,  //do not propagate shortcuts to parent
  ow_noparentshortcut, //do not react to shortcuts from parent
  ow_canclosenil,      // don't use, moved to optionswidget1
  ow_mousetransparent, ow_mousewheel, ow_noscroll,
  ow_nochildpaintclip, ow_nochildclipsiblings,                   
  ow_destroywidgets, ow_nohidewidgets,
  ow_hinton, ow_hintoff, ow_disabledhint, ow_multiplehint, ow_timedhint);
optionswidgetty = set of optionwidgetty;

property OptionsWidget: optionswidgetty;
  • If ow_mousefocus is set, the widget can get the focus by clicking on it.
  • If ow_tabfocus is set, the widget can get the focus using the tab key. See also TabOrder.
  • If ow_arrowfocus is set, the widget can get the mouse focus using the arrow keys.


OptionsWidget1

optionwidget1ty = (ow1_fontglyphheight, //track font.glyphheight, create fonthighdelta and childscaled events
  ow1_fontlineheight, //track font.linespacing, create fonthighdelta and childscaled events
  ow1_autoscale, //synchronizes bounds_cy or bonds_cx with fontheightdelta
  ow1_autowidth, ow1_autoheight,
  ow1_autosizeanright, ow1_noautosizeanright,
  ow1_autosizeanbottom, ow1_noautosizeanbottom,
  ow1_noparentwidthextend, ow1_noparentheightextend,
  ow1_canclosenil, //call canclose(nil) on exit
  ow1_nocancloseifhidden,
  ow1_modalcallonactivate, ow1_modalcallondeactivate, //used in tactionwidget
  ow1_noautosizing //used in tdockcontroller );                                         
optionswidget1ty = set of optionwidget1ty;

property OptionsWidget1: optionswidget1ty;

PopupMenu

Reference on a TPopupMenu instance, showing with a rightclick on the widget. See also OnPopup

property PopupMenu: TPopupMenu;

Visible

property Visible: boolean default true;

Sets the widget visible or hides it.

Methods

Events

OnHint

showhinteventty = procedure(const Sender: TObject; var Info: hintinfoty) of object;

The event OnHint is triggered, when a hint is displayed for the widget. With the var-parameter Info you can specify details of the displayed hint.

procedure tmainfo.FormShowHint(const Sender: TObject; var Info: hintinfoty);
begin
  Info.Caption := 'Trololo';
  Info.PosRect.X := Info.PosRect.X + 60;
  Info.PosRect.y := Info.PosRect.y - 20;
end;

msegui widget hint2.png

OnEnter, OnFocus, OnActivate

We have three pairs of events regarding the change of a focus:

property OnEnter: notifyeventty;
property OnExit: notifyeventty;

property OnFocus: notifyeventty;
property OnDeFocus: notifyeventty;

property OnActivate: notifyeventty;
property OnDeActivate: notifyeventty;

For an example we have two forms with both have two edits. The main form has an memo to log the events (here an example for OnEnter):

procedure ttestfo.FormEnter(const Sender: TObject);
begin
  MainFo.DoLog((Sender as TWidget).Name + ' OnEnter');
end;

We click on the first form:

  • Form1 OnEnter
  • Form1_Edit1 OnEnter
  • Form1_Edit1 OnFocus
  • Form1 OnActivate
  • Form1_Edit1 OnActivate

Now we click on the second edit of the first form:

  • Form1_Edit1 OnDeFocus
  • Form1_Edit1 OnDeActivate
  • Form1_Edit1 OnExit
  • Form1_Edit2 OnEnter
  • Form1_Edit2 OnActivate
  • Form1_Edit2 OnFocus

Now we click on then second form:

  • Form2 OnEnter
  • Form2_Edit1 OnEnter
  • Form2_Edit1 OnFocus
  • Form1_Edit2 OnDeActivate
  • Form1 OnDeActivate
  • Form2 OnActivate
  • Form2_Edit1 OnActivate

Now we click on the second edit of the first form (which was formerly focused on the first form):

  • Form2_Edit1 OnDeActivate
  • Form2 OnDeActivate
  • Form1 OnActivate
  • Form1_Edit2 OnActivate

And now we click on the second edit for the second form:

  • Form1_Edit2 OnDeActivate
  • Form1 OnDeActivate
  • Form2 OnActivate
  • Form2_Edit1 OnActivate
  • Form2_Edit1 OnDeFocus
  • Form2_Edit1 OnDeActivate
  • Form2_Edit1 OnExit
  • Form2_Edit2 OnEnter
  • Form2_Edit2 OnActivate
  • Form2_Edit2 OnFocus

In the last step we see first an complete activation change of the form (goes to Form2_Edit1) and than a complete focus change from Form2_Edit1 to Form2_Edit2.

We see:

  • OnFocus and OnDeFocus only the widget which have the focus, here TEdit.
  • OnEnter is the first event if a widget gets the focus, OnEnter is the last event if a widget loose the focus. On a focus change, OnEnter of the focus getting widget is following directly on OnExit of the focus loosing widget.
  • Changing the form fires only OnActivate and OnDeActivate (but not only the changing of the forms fires them). (First OnDeactivate of the widget, than OnDeactivate of the form, then OnActivate of the form, then OnActvate of the widget.)

OnNavigRequest

If ow_ArrowFocus is in OptionsWidget of the regarding widgets, you can change the focus with the arrow keys. The parent component has an algorithm to select the next widget for each arrow key, and at the end of this algorithm the event OnNavigRequest is fired. Here you can overwrite some values.

graphicdirectionty = (gd_right,gd_up,gd_left,gd_down,gd_none);

naviginfoty = record
  sender: twidget;
  direction: graphicdirectionty;
  startingrect: rectty;
  distance: integer;
  nearest: twidget;
  down: boolean;
  hastarget: boolean;
end;

navigrequesteventty = procedure(const Sender: twidget; var AInfo: naviginfoty) of object; 

property OnNavigRequest: navigrequesteventty

The most likely case may be, that you want to set the focus to another widget. In the following example the focus goes always to Edit9. Make sure, that you use the OnNavigRequest of the parent widget.

procedure tmainfo.FormNavigRequest(const Sender: TWidget; var AInfo: naviginfoty);
begin
  AInfo.Nearest := Edit9;
end;

OnPaint, OnPaintBackground, OnAfterPaint, OnPaintBackground

The OnPaint-Events are fired before, while or after the widget is painted.

painteventty = procedure (const Sender: TWidget; const ACanvas: TCanvas) of object;

property OnBeforePaint: painteventty;
property OnPaintBackground: painteventty;
property OnPaint: painteventty;
property OnAfterPaint: painteventty;

The following example shows, when the events are fired:

  • The first is OnBeforePaint. You don't see the green line, cause its overdrawn, but you see the two following lines with a width of 3.
  • The next is OnPaintBackground. You see the yellow line, but the Caption of the button is drawn over it.
  • OnPaint is drawn after the Caption is drawn, the red line is over it.
  • The last is OnAfterPaint, its fired after the frame is drawn so you can draw over the frame. The line width is resetted, if you want a higher line width, you have set it new.
procedure tmainfo.LabelPaint(const Sender: TWidget; const ACanvas: TCanvas);
begin
  ACanvas.DrawLine(mp(-30, -30), mp(150, 150), cl_red);
end;

procedure tmainfo.LabelAfterPaint(const Sender: TWidget; const ACanvas: TCanvas);
begin
  ACanvas.DrawLine(mp(-25, -30), mp(155, 150), cl_blue);
end;

procedure tmainfo.LabelBeforePaint(const Sender: TWidget; const ACanvas: TCanvas);
begin
  ACanvas.LineWidth := 3;
  ACanvas.DrawLine(mp(-20, -30), mp(160, 150), cl_green);
end;

procedure tmainfo.LabelPaintBackground(const Sender: TWidget; const ACanvas: TCanvas);
begin
  ACanvas.DrawLine(mp(-15, -30), mp(165, 150), cl_yellow);
end;

msegui label onpaint.png

OnPopup

The event OnPopup is fired if you show the PopupMenu by clicking with the right mouse button, but not, if you show the PopupMenu manually by TPopupMenu.Show.

popupeventty = procedure(const Sender: TObject; var AMenu: TPopupMenu; var MouseInfo: mouseeventinfoty) of object;

You can use AMenu to assign a TPopupMenu-Instance in this moment. With MouseInfo you have some information like Position or shift state and can also change them:

procedure tmainfo.LabelPopup(const Sender: TObject; var AMenu: TPopupMenu; var MouseInfo: mouseeventinfoty);
begin
  AMenu := PopupMenu1;
  MouseInfo.Pos.X := MouseInfo.Pos.X + 300;
end;

OnBeforeUpdateSkin, OnAfterUpdateSkin

Inherited from TMseComponent: OnBeforeUpdateSkin, OnAfterUpdateSkin

known issues

issues of the class

issues of this documentation

Feel free to add your points here.