lazarus/components/lazcontrols/docs/dividerbevel.xml

<?xml version="1.0" encoding="UTF-8"?>
<fpdoc-descriptions>
<package name="LazControls">

<module name="DividerBevel">
<short>
Implements a bevel with additional drawing features used as a separator on 
forms, frames, and panels.
</short>
<descr>
<p>
<file>dividerbevel.pas</file> contains the <var>TDividerBevel</var> control, 
a bevel with additional drawing features. <file>dividerbevel.pas</file> is 
part of the <file>LazControls</file> package.
</p>
</descr>

<!-- unresolved external references -->
<element name="Classes"/>
<element name="Types"/>
<element name="Math"/>
<element name="LCLType"/>
<element name="LCLIntf"/>
<element name="Controls"/>
<element name="Graphics"/>
<element name="ComCtrls"/>
<element name="ExtCtrls"/>
<element name="Themes"/>
<element name="GraphType"/>

<element name="TDividerBevel">
<short>Line with text in the middle, used as a divider or header.</short>
<descr>
<p>
TDividerBevel is a TGraphicControl descendant which implements a component 
represented as a beveled line with a caption. It is used as a separator or 
header on forms, frames, and panels. It is similar to TBevel, but provides 
additional drawing styles as well layout options for the control caption.
</p>
<p>
TDividerBevel can be oriented either horizontally or vertically. The bevel 
can be drawn using a raised or lowered drawing style. The bevel can be 
rendered using a line drawing shape or a pattern defined in the Style 
property. The height of the bevel can be specified, or it can resize to the 
Text on the control. The caption can be drawn at a specific position 
(LeftIndent) and surrounded by an unused space using the CaptionSpacing 
property. Transparency is also supported in the control.
</p>
<p>
The BevelWidth property indicates the thickness for the bevel. It is set to 
-1 by default, and indicates that the size is Max(3, TextHeight div 5). A 
positive value means that pixel measurements are used in the property.
</p>
<p>
The LeftIndent is set by default to 60. Any negative value in LeftIndent 
causes the text in Caption to be centered along the bevel orientation.
</p>
</descr>
<seealso/>
</element>

<!-- private members and methods -->
<element name="TDividerBevel.FBevelStyle"/>
<element name="TDividerBevel.FBevelWidth"/>
<element name="TDividerBevel.FCaptionSpacing"/>
<element name="TDividerBevel.FLeftIndent"/>
<element name="TDividerBevel.FOrientation"/>
<element name="TDividerBevel.FStyle"/>
<element name="TDividerBevel.FTransparent"/>

<element name="TDividerBevel.SetBevelStyle">
<short>Sets the value in the BevelStyle property.</short>
<descr/>
<seealso>
<link id="TDividerBevel.BevelStyle"/>
<link id="#lcl.controls.TControl.AutoSize">TControl.AutoSize</link>
</seealso>
</element>
<element name="TDividerBevel.SetBevelStyle.AValue">
<short>New value for the BevelStyle property.</short>
</element>

<element name="TDividerBevel.SetBevelWidth">
<short>Sets the value in the BevelWidth property.</short>
<descr/>
<seealso>
<link id="TDividerBevel.SetBevelWidth"/>
</seealso>
</element>
<element name="TDividerBevel.SetBevelWidth.AValue">
<short>New value for the BevelWidth property.</short>
</element>

<element name="TDividerBevel.SetCaptionSpacing">
<short>Sets the value for the CaptionSpacing property.</short>
<descr/>
<seealso>
<link id="TDividerBevel.CaptionSpacing"/>
</seealso>
</element>
<element name="TDividerBevel.SetCaptionSpacing.AValue">
<short>New value for the CaptionSpacing property.</short>
</element>

<element name="TDividerBevel.SetLeftIndent">
<short>Sets the value for the LeftIndent property.</short>
<descr/>
<seealso>
<link id="TDividerBevel.LeftIndent"/>
</seealso>
</element>
<element name="TDividerBevel.SetLeftIndent.AValue">
<short>New value for the LeftIndent property.</short>
</element>

<element name="TDividerBevel.SetOrientation">
<short>Sets the value for the Orientation property.</short>
<descr/>
<seealso>
<link id="TDividerBevel.Orientation"/>
</seealso>
</element>
<element name="TDividerBevel.SetOrientation.AValue">
<short>New value for the Orientation property.</short>
</element>

<element name="TDividerBevel.SetStyle">
<short>Sets the value for the Style property.</short>
<descr/>
<seealso>
<link id="TDividerBevel.Style"/>
</seealso>
</element>
<element name="TDividerBevel.SetStyle.AValue">
<short>New value for the Style property.</short>
</element>

<element name="TDividerBevel.SetTransparent">
<short>Sets the value for the Transparent property.</short>
<descr/>
<seealso>
<link id="TDividerBevel.Transparent"/>
</seealso>
</element>
<element name="TDividerBevel.SetTransparent.AValue">
<short>New value for the Transparent property.</short>
</element>

<!-- protected members and methods -->
<element name="TDividerBevel.FBevelHeight">
<short>Member with the height for the bevel.</short>
<descr/>
<seealso/>
</element>

<element name="TDividerBevel.FBevelTop">
<short>Member with the top for the bevel.</short>
<descr/>
<seealso/>
</element>

<element name="TDividerBevel.FNeedCalcSize">
<short>
Member with the flag set when the Font, Text, Bevel or the preferred size has 
been changed.
</short>
<descr/>
<seealso>
<link id="TDividerBevel.TextChanged"/>
<link id="TDividerBevel.BevelWidth"/>
<link id="TDividerBevel.Calcsize"/>
<link id="TDividerBevel.FontChanged"/>
<link id="TDividerBevel.CalcSize"/>
<link id="TDividerBevel.Create"/>
</seealso>
</element>

<element name="TDividerBevel.FTextExtent">
<short>Member with the text extent for the Caption property.</short>
<descr/>
<seealso>
<link id="TDividerBevel.CalcSize"/>
<link id="TDividerBevel.CalculatePreferredSize"/>
<link id="TDividerBevel.Paint"/>
</seealso>
</element>

<element name="TDividerBevel.GetControlClassDefaultSize">
<short>The default size for a new instance of the class.</short>
<descr>
<p>
GetControlClassDefaultSize is an overridden TSize function used to get the 
default size for new instances of the TDividerBevel class. The width (CX) in 
the TSize instance is set to 240. The height (CY) in the TSize instance is 
set to 17.
</p>
<p>
Used by the GetDefaultWidth and GetDefaultHeight methods.
</p>
</descr>
<seealso>
<link id="#lcl.controls.TControl.GetControlClassDefaultSize">TControl.GetControlClassDefaultSize</link>
</seealso>
</element>
<element name="TDividerBevel.GetControlClassDefaultSize.Result">
<short>
TSize instance with the width and height for the new class instance.
</short>
</element>

<element name="TDividerBevel.CalcSize">
<short>
Calculates the height for the Caption text and the bevel on the control.
</short>
<descr>
<p>
CalcSize is a method used to calculate the height for the Caption text and 
the bevel drawn on the control. An internal flag, set when the Text or Font 
for the control is changed, is used to determine when the calculation is 
needed. No actions are performed in the method if the flag has not been set.
</p>
<p>
CalcSize calls the TextExtent method in the control Canvas to get the text 
extent for Caption.
</p>
<p>
BevelWidth is used to set the height for the bevel in pixels when it has a 
positive or zero value. When BevelWidth has a negative value, the height for 
the bevel is set to the larger of 20% of the text height or 3 pixels. The 
bevel is centered in the text height.
</p>
<p>
CalcSize is called from the CalculatePreferredSize and Paint methods.
</p>
</descr>
<seealso/>
</element>

<element name="TDividerBevel.Paint">
<short>Draws the control on its Canvas.</short>
<descr>
<p>
<var>Paint</var> is an overridden method used to draw the control on its 
<var>Canvas</var>. It re-implements the method from the ancestor class, and 
does <b>not</b> call the inherited method.
</p>
<p>
Paint calls CalcSize to ensure that the height for the Caption text and the 
bevel are updated before the control is drawn.
</p>
<p>
If Transparent is set to <b>False</b>, the background for the control is 
filled using the value in Color.
</p>
<p>
Values in BevelStyle, Style, Orientation, and Caption are used to determine 
the drawing area for the bevel on the control. The PaintBevel method is 
called to render the bevel to the control Canvas.
</p>
<p>
When Caption has been assigned, it is positioned using the values in 
LeftIndent and CaptionSpacing. The TextOut method in Canvas is called to draw 
the Caption text using the Orientation for the control.
</p>
<p>
Use the Font property to configure the font face, style, and size used for 
the Caption text.
</p>
</descr>
<seealso/>
</element>

<element name="TDividerBevel.FontChanged">
<short>
Performs actions when the Font for the control has been changed.
</short>
<descr>
<p>
<var>FontChanged</var> is an overridden method used to update the control 
when the value in <var>Font</var> has been changed. It calls the inherited 
method on entry to apply the new font to the control <var>Canvas</var>, and 
post a <var>CM_FONTCHANGED</var> control message to the widgetset class. The 
internal flag used to force text and bevel sizes to be recalculated is set. 
<var>Invalidate</var> is called to force the control to be redrawn.
</p>
<p>
FontChanged is assigned as the OnChange event handler in the Font property.
</p>
</descr>
<seealso>
<link id="#lcl.controls.TGraphicControl.FontChanged">TGraphicControl.FontChanged</link>
</seealso>
</element>
<element name="TDividerBevel.FontChanged.Sender">
<short>Object instance for the event notification.</short>
</element>

<element name="TDividerBevel.SetAutoSize">
<short>Sets the value for the AutoSize property.</short>
<descr>
<p>
<var>SetAutoSize</var> is an overridden method in TDividerBevel. It calls the 
inherited method on entry to update the member for AutoSize and to call the 
AdjustSize method when needed. It extends InvalidatePreferredSize method (in 
the ancestor) to clear any cached preferred size value for the control or any 
of its parents when Value is set to <b>True</b>.
</p>
</descr>
<seealso>
<link id="#lcl.controls.TControl.AutoSize">TControl.AutoSize</link>
<link id="#lcl.controls.TControl.InvalidatePreferredSize">TControl.InvalidatePreferredSize</link>
</seealso>
</element>
<element name="TDividerBevel.SetAutoSize.Value">
<short>New value for the AutoSize property.</short>
</element>

<element name="TDividerBevel.TextChanged">
<short>
Performs actions when the CM_TEXTCHANGED message is handled for the control.
</short>
<descr>
<p>
<var>TextChanged</var> is an overridden method used to perform action needed 
when the value in the text property has been changed for the control. It 
re-implements the method from the ancestor class to set in the internal flag 
to recalculate text and bevel sizes in the control, and calls the 
<var>Invalidate</var> method to force the control to be redrawn.
</p>
<p>
TextChanged is called from the <var>CMTextChanged</var> method.
</p>
</descr>
<seealso>
<link id="#lcl.controls.TControl.CMTextChanged">TControl.CMTextChanged</link>
</seealso>
</element>

<element name="TDividerBevel.CalculatePreferredSize">
<short>Calculates the preferred size for the control.</short>
<descr>
<p>
CalculatePreferredSize is an overridden method used to calculate the 
preferred width and height for the control. It re-implements the method from 
the ancestor class, and does not call the inherited method.
</p>
<p>
CalculatePreferredSize sets the internal flag to recalculate the text and 
bevel height, and calls CalcSize to update the values.
</p>
<p>
The value in Orientation is used to determine the value calculated in the 
method. When set to trHorizontal, PreferredHeight is set to the maximum of 
the text height or the bevel height (Caption is empty). When set to 
trVertical, the PreferredWidth is set to the maximum of the text height or 
the bevel height (Caption is empty).
</p>
</descr>
<seealso/>
</element>
<element name="TDividerBevel.CalculatePreferredSize.PreferredWidth">
<short>The preferred width for the control.</short>
</element>
<element name="TDividerBevel.CalculatePreferredSize.PreferredHeight">
<short>The preferred height for the control.</short>
</element>
<element name="TDividerBevel.CalculatePreferredSize.WithThemeSpace">
<short>
<b>True</b> if additional space is reserved for theme elements. Not used in 
the method.
</short>
</element>

<!-- public methods -->
<element name="TDividerBevel.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
Create is the overridden constructor for the class instance, and calls the 
inherited method on entry. It sets the default values for properties, 
including:
</p>
<ul>
<li>BevelStyle (bsLowered)</li>
<li>BevelWidth (-1 for relative bevel size)</li>
<li>CaptionSpacing (10 pixels)</li>
<li>LeftIndex (60 pixels)</li>
<li>Orientation (trHorizontal)</li>
<li>Transparent (True)</li>
<li>AutoSize (True)</li>
</ul>
<p>
An internal flag used to force the text and bevel height to be calculated is 
set. The GetControlClassDefaultSize method is called get and set the initial 
bounds for the class instance.
</p>
</descr>
<seealso/>
</element>
<element name="TDividerBevel.Create.AOwner">
<short>Owner of the class instance.</short>
</element>

<element name="TDividerBevel.ShouldAutoAdjust">
<short>
Determine if the width and/or height can be adjusted by a layout policy.
</short>
<descr>
<p>
Re-implements the method from the ancestor class, and does not call the 
inherited method. In <var>TDividerBevel</var>, a dimension can be 
auto-adjusted when <var>AutoSize</var> is not enabled, and the dimension is 
not the <var>Orientation</var> for the control. Called when an auto-adjust 
layout policy is applied to the control.
</p>
</descr>
<seealso>
<link id="#lcl.controls.TControl.ShouldAutoAdjust">TControl.ShouldAutoAdjust</link>
</seealso>
</element>
<element name="TDividerBevel.ShouldAutoAdjust.AWidth">
<short>
<b>True</b> if the width can be auto-adjusted by a layout policy.
</short>
</element>
<element name="TDividerBevel.ShouldAutoAdjust.AHeight">
<short>
<b>True</b> if the height can be auto-adjusted by a layout policy.
</short>
</element>

<!-- published properties -->
<element name="TDividerBevel.Caption" link="#lcl.controls.TControl.Caption"/>
<element name="TDividerBevel.Align" link="#lcl.controls.TControl.Align"/>
<element name="TDividerBevel.AutoSize" link="#lcl.controls.TControl.AutoSize"/>
<element name="TDividerBevel.Anchors" link="#lcl.controls.TControl.Anchors"/>

<element name="TDividerBevel.BevelStyle">
<short>
Indicates whether the bevel is drawn using a raised or lowered drawing style.
</short>
<descr>
<p>
<var>BevelStyle</var> is a <var>TBevelStyle</var> property which indicates if 
the bevel is drawn using a raised or lowered style. The default value for the 
property is <var>bsLowered</var>. Changing the value for the property causes 
the control to be redrawn.
</p>
<p>
Use BevelWidth to set the bevel height in pixels, or relative to the text 
height for the control. Use Style to set the shape or pattern used to draw 
the bevel.
</p>
<p>
BevelStyle is used in the Paint method.
</p>
</descr>
<seealso>
<link id="TDividerBevel.BevelWidth"/>
<link id="TDividerBevel.Style"/>
<link id="#lcl.extctrls.TBevelStyle">TBevelStyle</link>
</seealso>
</element>

<element name="TDividerBevel.BevelWidth">
<short>Height for the bevel on its Orientation.</short>
<descr>
<p>
The default value for the property is <b>-1</b>. Negative values in the 
property indicate that the bevel is drawn using 20% of the Text height for 
the control, with a minimum height of 3 pixels.
</p>
<p>
Changing the value in BevelWidth causes the control to be updated. When 
AutoSize is <b>True</b>, the preferred size is reset and the AdjustSize 
method is called. When AutoSize is <b>False</b>, an internal flag is set to 
indicate that the size needs to be recalculated in the CalcSize method. The 
Invalidate method is called to force the control to be redrawn.
</p>
</descr>
<seealso>
<link id="TDividerBevel.AutoSize"/>
<link id="#lcl.controls.TControl.InvalidatePreferredSize">TControl.InvalidatePreferredSize</link>
<link id="#lcl.controls.TControl.AdjustSize">TControl.AdjustSize</link>
<link id="#lcl.controls.TControl.Invalidate">TControl.Invalidate</link>
</seealso>
</element>

<element name="TDividerBevel.BiDiMode" link="#lcl.controls.TControl.BidiMode"/>
<element name="TDividerBevel.BorderSpacing" link="#lcl.controls.TControl.BorderSpacing"/>

<element name="TDividerBevel.CaptionSpacing">
<short>
Number of pixels reserved as spacing in front of and following the Caption 
for the control.
</short>
<descr>
<p>
The default value for the property is <b>10</b>. Use <var>LeftIndent</var> to 
set the position (in pixels) where the Caption text is drawn. A negative 
value in LeftIndent causes the caption to be centered along the bevel, and 
the value in CaptionSpacing is ignored.
</p>
</descr>
<seealso>
<link id="TDividerBevel.LeftIndent"/>
</seealso>
</element>

<element name="TDividerBevel.Color" link="#lcl.controls.TControl.Color"/>
<element name="TDividerBevel.Constraints" link="#lcl.controls.TControl.Constraints"/>

<element name="TDividerBevel.DragCursor" link="#lcl.controls.TControl.DragCursor"/>
<element name="TDividerBevel.DragKind" link="#lcl.controls.TControl.DragKind"/>
<element name="TDividerBevel.DragMode" link="#lcl.controls.TControl.DragMode"/>
<element name="TDividerBevel.Font" link="#lcl.controls.TControl.Font"/>
<element name="TDividerBevel.Hint" link="#lcl.controls.TControl.Hint"/>

<element name="TDividerBevel.LeftIndent">
<short>
Position relative to Left where the CaptionSpacing and Caption are drawn.
</short>
<descr>
<p>
<var>LeftIndent</var> is an <var>Integer</var> property which indicates the 
position relative to the <var>Left</var> property where the 
<var>CaptionSpacing</var> and <var>Caption</var> text are displayed on the 
control. The default value for the property is <b>60</b> pixels.
</p>
<p>
Use <var>CaptionSpacing</var> to set the number of pixels reserved as 
undecorated blank space on each side of the Caption text.
</p>
<p>
For example: If CaptionSpacing is set to 10, and LeftIndent is set to 60, 
the CaptionSpacing starts at 60 pixels and the text at 70 pixels relative to 
Left.
</p>
<p>
LeftIndent, when set to a negative value, causes the CaptionSpacing and 
Caption text to be centered along the Orientation for the divider bevel. When 
set to 0, neither left indent nor caption spacing are applied before the 
Caption text.
</p>
<p>
Changing the value for the property causes the control to be redrawn.
</p>
<p>
LeftIndent is used in the Paint method.
</p>
</descr>
<seealso>
<link id="TDividerBevel.CaptionSpacing"/>
<link id="TDividerBevel.Orientation"/>
<link id="TDividerBevel.Paint"/>
<link id="#lcl.controls.TControl.Caption">TControl.Caption</link>
<link id="#lcl.controls.TControl.Left">TControl.Left</link>
</seealso>
</element>

<element name="TDividerBevel.Orientation">
<short>Direction that the bevel and caption are drawn.</short>
<descr>
<p>
<var>Orientation</var> is a <var>TTrackBarOrientation</var> property which 
indicates the direction that the bevel and caption are drawn on the control. 
The default value for the property is <var>trHorizontal</var>, and causes the 
bevel and caption to be draw from left to right horizontally. When set to 
trVertical, the <var>Font</var> on the control <var>Canvas</var> is rotated 
90 degrees and the bevel and caption are drawn from top to bottom vertically.
</p>
<p>
Changing the value for the property causes the size to be adjusted when 
<var>AutoSize</var> is set to <b>True</b>. The control is redrawn when the 
new property value is applied.
</p>
<p>
Orientation is used in the <var>Paint</var> method.
</p>
</descr>
<seealso>
<link id="TDividerBevel.Paint"/>
<link id="#lcl.controls.TGraphicControl.Canvas">TGraphicControl.Canvas</link>
<link id="#lcl.controls.TControl.AutoSize">TControl.AutoSize</link>
<link id="#lcl.comctrls.TTrackBarOrientation">TTrackBarOrientation</link>
</seealso>
</element>

<element name="TDividerBevel.ParentBiDiMode" link="#lcl.controls.TControl.ParentBiDiMode"/>
<element name="TDividerBevel.ParentColor" link="#lcl.controls.TControl.ParentColor"/>
<element name="TDividerBevel.ParentFont" link="#lcl.controls.TControl.ParentFont"/>
<element name="TDividerBevel.ParentShowHint" link="#lcl.controls.TControl.ParentShowHint"/>
<element name="TDividerBevel.PopupMenu" link="#lcl.controls.TControl.PopupMenu"/>
<element name="TDividerBevel.ShowHint" link="#lcl.controls.TControl.ShowHint"/>

<element name="TDividerBevel.Style">
<short>Drawing style for the bevel on the control.</short>
<descr>
<p>
<var>Style</var> is a <var>TGrabStyle</var> property with the shape or 
pattern used to draw the bevel on the control.
</p>
<p>
The default value for the property is <var>gsSimple</var>, and causes a 
simple rectangle to be drawn with the appearance in the <var>BevelStyle</var> 
property. Contrasting colors on the borders are used to achieve the raised or 
lowered appearance. Other values include:
</p>
<dl>
<dt>gsDouble</dt>
<dd>Draws double lines using the appearance in BevelStyle.</dd>
<dt>gsHorLines</dt>
<dd>Draws a single line using the appearance in BevelStyle.</dd>
<dt>gsVerLines</dt>
<dd>Draws a vertical line using the appearance in BevelStyle.</dd>
<dt>gsGripper</dt>
<dd>
Draws a row of raised dots on the bevel. BevelStyle is not used. Drawn using 
the trGripper theme element details in ThemeServices.
</dd>
<dt>gsButton</dt>
<dd>
Draws the bevel using a pseudo-button style. BevelStyle is not used. Drawn 
using the tbPushButtonNormal theme element details in ThemeServices.
</dd>
</dl>
</descr>
<seealso>
<link id="TDividerBevel.BevelStyle"/>
<link id="TDividerBevel.BevelWidth"/>
</seealso>
</element>

<element name="TDividerBevel.Transparent">
<short>
Indicates if the parent control is visible beneath the drawing area for the 
divider bevel.
</short>
<descr>
<p>
<var>Transparent</var> is a Boolean property which indicates if the control 
is drawn with transparency. When set to <b>True</b>, the parent control is 
visible beneath the undecorated areas on the control. When set to 
<b>False</b>, the client area for the control is filled using the value in 
Color. The default value for the property is <b>True</b>.
</p>
</descr>
<seealso>
<link id="#lcl.controls.TControl.Color">TControl.Color</link>
</seealso>
</element>

<element name="TDividerBevel.Visible" link="#lcl.controls.TControl.Visible"/>
<element name="TDividerBevel.OnChangeBounds" link="#lcl.controls.TControl.OnChangeBounds"/>
<element name="TDividerBevel.OnClick" link="#lcl.controls.TControl.OnClick"/>
<element name="TDividerBevel.OnContextPopup" link="#lcl.controls.TControl.OnContextPopup"/>
<element name="TDividerBevel.OnDblClick" link="#lcl.controls.TControl.OnDblClick"/>
<element name="TDividerBevel.OnDragDrop" link="#lcl.controls.TControl.OnDragDrop"/>
<element name="TDividerBevel.OnDragOver" link="#lcl.controls.TControl.OnDragOver"/>
<element name="TDividerBevel.OnEndDrag" link="#lcl.controls.TControl.OnEndDrag"/>
<element name="TDividerBevel.OnMouseDown" link="#lcl.controls.TControl.OnMouseDown"/>
<element name="TDividerBevel.OnMouseEnter" link="#lcl.controls.TControl.OnMouseEnter"/>
<element name="TDividerBevel.OnMouseLeave" link="#lcl.controls.TControl.OnMouseLeave"/>
<element name="TDividerBevel.OnMouseMove" link="#lcl.controls.TControl.OnMouseMove"/>
<element name="TDividerBevel.OnMouseUp" link="#lcl.controls.TControl.OnMouseUp"/>
<element name="TDividerBevel.OnResize" link="#lcl.controls.TControl.OnResize"/>
<element name="TDividerBevel.OnStartDrag" link="#lcl.controls.TControl.OnStartDrag"/>

</module>

</package>
</fpdoc-descriptions>