mirror of
https://gitlab.com/freepascal.org/lazarus/lazarus.git
synced 2025-08-18 06:59:21 +02:00
LazDoc - major update to 'Topic' in StdCtls
git-svn-id: trunk@12799 -
This commit is contained in:
kirkpatc
parent
341ec7141b
commit
cadb0cabb9
@ -6152,23 +6152,79 @@ You should take care when setting these options that they do not conflict with t
|
||||
<seealso/>
|
||||
</element>
|
||||
<topic name="HowToUseStdCtrls">
|
||||
<short>How to use <i>StdCtrls</i></short>
|
||||
<descr>
|
||||
<p>The Unit <i>StdCtrls</i> contains definitions and descriptions of many of the most commonly used controls for constructing Forms and other Objects in Lazarus Applications.</p>
|
||||
<p>Many of the final target controls that the application developer wants to use, such as <i>TButton</i>, <i>TMemo</i>, <i>TScrollBar</i> etc, have a corresponding ancestor class such as <i>TCustomButton</i>, <i>TCustomMemo</i> or <i>TCustomScrollBar</i>. Many of the properties and methods relevant to the final target control are defined fully in the <i>TCustomXXX</i> class, and are <b>inherited</b> by the final target control.
|
||||
</p>
|
||||
<p>If you drop a component on the form editor you don´t need to add code to explicitly create it. The component is automatically created by the IDE together with the form, and destroyed when the form is destroyed.</p>
|
||||
<p>However, if you create the component yourself by code don´t forget to free it when it is no longer needed.</p>
|
||||
<br/>
|
||||
<p><i>Constructors </i> allocate memory and system resources needed by the object. They also call the constructor of any sub-objects present in the class.</p>
|
||||
<p><i>Destructors:</i> If you call <i>Destroy </i>for an object which hasn´t being initialized yet it will generate an error. Always use the <i>Free</i> method to deallocate objects, because it verifies if an object variable doesn´t contain the value <i>nil</i>.</p>
|
||||
<p>Take the following precautions when creating your own <i>Destroy</i> method:</p>
|
||||
<p>* Declare <i>Destroy</i> with the <b>override</b> directive, because it is a <b>virtual</b> method.</p>
|
||||
<p>* Always call '<i>inherited Destroy;</i>' as the last thing on the destructor code.</p>
|
||||
<p>* An <i>exception</i> may be raised on the constructor in case there is not enought memory to create an object, or something else goes wrong. If the <i>exception</i> is not handled inside the constructor, the object will be only partially built. In this case <i>Destroy</i> will be called, so your destructor must check if the resources were really allocated before disposing of them.</p>
|
||||
<p>* Remember to call <i>Free</i> for all objects created on the constructor.</p>
|
||||
</descr>
|
||||
</topic>
|
||||
<short>How to use <i>StdCtrls</i>, <i>ComCtrls</i> or <i>ExtCtrls</i></short>
|
||||
<descr>
|
||||
<p>The Units <i>StdCtrls</i>, <i>ComCtrls</i> and <i>ExtCtrls</i> contain definitions and descriptions of many of the most commonly used controls for constructing Forms and other Objects in Lazarus Applications.</p>
|
||||
<p>Many of the final target controls that the application developer wants to use, such as <i>TButton</i>, <i>TMemo</i>, <i>TScrollBar</i> etc, have a corresponding ancestor class such as <i>TCustomButton</i>, <i>TCustomMemo</i> or <i>TCustomScrollBar</i>. Many of the properties and methods relevant to the final target control are defined (and explained) more fully in the <i>TCustomXXX</i> class, and are <b>inherited</b> by the final target control.</p><br/>
|
||||
<p>If you drop a component on the form editor you don't need to add code explicitly to create it. The component is automatically created by the IDE together with the form, and destroyed when the form is destroyed.</p>
|
||||
<p>However, if you create the component yourself by code don't forget to free it when it is no longer needed.</p>
|
||||
<br/>
|
||||
<p>If you place a component on the Form Designer and look at the Object Inspector, you can observe the properties change as you move the component around.</p>
|
||||
<p>For example, if you place a button (TButton) on the form, click on it to select it, then move it around the form with the mouse, you can watch the values of Top and Left change in the Object Inspector to reflect the new position. If you use the object's re-sizing bars to adjust its size, you can watch the Height and Width properties change as well.</p>
|
||||
<p>On the other hand, by using the Object Inspector, you can select the value associated with a property such as height, and type in a new value; you can watch the size of the object on the form change to reflect the new value.</p>
|
||||
<p>You can also explicitly change the properties of the object in code by typing (in the appropriate Implementation section of the Source editor), for example</p><br/>
|
||||
<code> Form1.Button1.Height := 48;</code><br/>
|
||||
<p>If you type this new value into the Source Editor and then look back at the Form Designer, you will see that the button on the Form has taken the new size. The new value will also be shown in the Object Inspector.</p><br/>
|
||||
<p>In summary, there are usually about three different ways to determine each property of an object:</p>
|
||||
<ul>
|
||||
<li>by using the mouse,</li>
|
||||
<li>by setting the values in the Object Inspector,</li>
|
||||
<li>or explicitly by writing code.</li>
|
||||
</ul><br>
|
||||
<p>The components defined in these Units have several properties that are common to most of them, and other properties that are specific to the individual components. We shall describe the most common ones here. Unusual or control-specific properties will be described for the individual controls. </p>
|
||||
<p>Additional Help can always be obtained by selecting a property or keyword, in either the Object Inspector or the Source Editor, and pressing F1. You will be taken by your Help browser to the appropriate page in the documentation. </p>
|
||||
<p>If the description of a property on that page is insufficient, you can navigate to the corresponding description in the ancestor classes, by selecting the links in the Inheritance listing or by selecting the ancestor Type in the declaration of the object.</p>
|
||||
|
||||
<p><i>Constructors</i> such as <i>Create</i> allocate memory and system resources needed by the object. They also call the constructor of any sub-objects present in the class.</p>
|
||||
<p><i>Destructors:</i> If you call <i>Destroy</i> for an object which hasn't being initialized yet it will generate an error. Always use the <i>Free</i> method to deallocate objects, because it checks whether an object's value is <b>nil</b> before invoking <i>Destroy</i>.</p>
|
||||
<p>Take the following precautions when creating your own <i>Destroy</i> method:</p>
|
||||
<ul>
|
||||
<li>* Declare <i>Destroy</i> with the <b>override</b> directive, because it is a <b>virtual</b> method.</li>
|
||||
<li>* Always call '<i>inherited Destroy;</i>' as the last thing on the destructor code.</li>
|
||||
<li>* Be aware that an <i>exception</i> may be raised on the <i>constructor</i> in case there is not enought memory to create an object, or something else goes wrong. If the <i>exception</i> is not handled inside the constructor, the object will be only partially built. In this case <i>Destroy</i> will be called when you weren't expecting it, so your destructor must check if the resources were really allocated before disposing of them.</li>
|
||||
<li>* Remember to call <i>Free</i> for all objects created on the constructor.</li>
|
||||
</ul><br/>
|
||||
<table>
|
||||
<caption>Some commonly listed properties</caption>
|
||||
<th><td>Property</td><td>Meaning</td></th>
|
||||
<tr><td>Action</td><td>The main action or event associated with the object. For example selecting an 'Exit' Button might cause the 'Close' action</td></tr>
|
||||
<tr><td>Align</td><td>Defines the way in which an object is to be lined up with the parent object. Possible values are alTop (placed at the top and using the full available width), alBottom, alLeft (placed at the left and using the full available height), alRight. alNone (place anywhere on parent control) or alClient (takes all available space next to controls aligned to top, bottom, left or right)</td></tr>
|
||||
<tr><td>Anchor</td><td>Used to keep a control a certain distance from the defined edges of a parent control, when the parent is resized. For example <b>[akBottom, akRight]</b> will keep thc control a fixed distance from the bottom right corner.</td></tr>
|
||||
<tr><td>BorderSpacing</td><td>The space around the edge between an <i>Anchored</i> control and its parent.</td></tr>
|
||||
<tr><td>Caption</td><td>The text that is displayed on or near the control; it should preferably give some clue as to the function of the control, or an instruction such as 'C;ose' or 'Execute'. By default Caption is set to be the same as the 'Name' property, and the application programmer should take steps to substitute meaningful text instead of the default values.</td></tr>
|
||||
<tr><td>Color</td><td>The Colour to be used to draw the control or to write the text it contains.</td></tr>
|
||||
<tr><td>Enabled</td><td>A Boolean property to determine whether or not a control is capable of being selected and performing an action. If it is not <i>Enabled</i>, it is often <b>Grayed</b> out on the Form.</td></tr>
|
||||
<tr><td>Font</td><td>The Font to be used for writing the text associated with the control - either the caption or label, or the text-strings contained within the control.</td></tr>
|
||||
<tr><td>Items</td><td>The list of 'Things' that the object contains, such as a group of images, a series of lines of text, a number of actions in an actionlist, etc</td></tr>
|
||||
<tr><td>Name</td><Td>The identifier by which the control is known in the programme. The IDE gives it a default name based on the underlying type, for example successive instances of TBitButton would be named Form1.BitBitton1 and Form1.BitButton2; it is up to the application programmer to give them more meaningful names such as Form1.ExitButton or Form1.OKButton. By default the Name of the control is applied to the Caption for the control, but the text of the Caption may be changed separately.</td></tr>
|
||||
<tr><td>PopUpMenu</td><td>A window containing context-sensitive menu information that pops up when the right mouse button is clicked on the object.</td></tr>
|
||||
<tr><td>Position (or Top, Left)</td><td>Determines where the control is located on the parent form or window</td></tr>
|
||||
<tr><td>ReadOnly</td><td>Boolean property which, if True, signifies that the contents of the control can be read by the user or the calling routine, but cannot be written or changed.</td></tr>
|
||||
<tr><td>ShowHint</td><td>Allows a small window containing a context-sensitive Help or other description to be displayed when the mouse cursor 'hovers' over the control.</td></tr>
|
||||
<tr><td>Size (or Height and Width)</td><td>The dimensions of the control</td></tr>
|
||||
<tr><td>Style</td><td>Dummy</td></tr>
|
||||
<tr><td>TabOrder</td><td>Dummy</td></tr>
|
||||
<tr><td>TabStop</td><td>Dummy</td></tr>
|
||||
<tr><td>Text</td><td>Dummy</td></tr>
|
||||
<tr><td>Visible</td><td>Dummy</td></tr>
|
||||
</table>
|
||||
<p>Many actions are commonly listed in the 'Events' tab of the Object Inspector. If you select an entry in th elist, a ComboBox appears with a DropDown list showing any actions that have aleady been defined, and allowing you to choose one to be associated with this event. Alternatively you can select the ellipsis (three dots ...) and you will be taken to an area of the Source Editor where you can begin typing your own action instructions for the selected event.</p>
|
||||
<p>While there is a large number of available events for any given control, in practice it is only necessary to populate a few of them. For most controls, it is sufficient to provide coding for 'OnClick'; for more complex controls it may be necessary also to provide for 'OnEntry' (when the mouse cursor enters the Control and gives it focus) and 'OnExit' (when the mouse cursor leaves the Control; or you may need to write an event handler for 'OnChange' or 'OnScroll', depending on the nature of the particular control with which you are dealing.</p>
|
||||
<p>A common strategy in Object-Oriented programming is to provide an <link id="ActnList.TActionList">ActionList</link> with a number of pre-defined actions from which the most appropriate can be selected to use in any particular instance.
|
||||
<table>
|
||||
<caption>Some commonly listed Actions</caption>
|
||||
<th><td>Action</td><td>Meaning</td></th>
|
||||
<tr><td>OnChange</td><td>Action to be taken if <u>any</u> change is deteted (eg mouse move, mode click, key press, edit text, alter picture, etc)</td></tr>
|
||||
<tr><td>OnClick</td><td>Action to be taken when the left mouse button is clicked. This is usually the main or default action of the control; for example clicking on a button or checkbox initiates the action associated with the checkbox. It may alternatively initate a process of selection, for instance in a TextBox or Memo, or signal the beginning of painting with a Pen or Brush.</td></tr>
|
||||
<tr><td>OnDragDrop</td><td>Action to be taken during Drag-Drop manoeuvres, ie when the mouse is osed to 'capture' an item or some text etc and move it around the screen to a new location.</td></tr>
|
||||
<tr><td>OnEntry</td><td>Action to be taken when the mouse cursor enters the area occupied by the object, usually transfering focus to that object. This might include changes in the appearance of the object such as highlighting or raising the border.</td></tr>
|
||||
<tr><td>OnExit</td><td>Action to be taken when the mouse moves out of the area of the object, usually transferring focus out of the object.</td></tr>
|
||||
<tr><td>OnKeyPress</td><td>Action to be taken for any key-press</td></tr>
|
||||
<tr><td>OnMouseMove</td><td>Action to be taken for any movement of the mouse</td></tr>
|
||||
</table>
|
||||
|
||||
</descr>
|
||||
</topic>
|
||||
</module>
|
||||
<!-- StdCtrls -->
|
||||
</package>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user