{"id":2919,"date":"2011-06-01T02:13:34","date_gmt":"2011-06-01T10:13:34","guid":{"rendered":"http:\/\/www.sapien.com\/blog\/?p=2919"},"modified":"2016-05-18T15:05:18","modified_gmt":"2016-05-18T22:05:18","slug":"primalforms-2011-spotlight-on-controls","status":"publish","type":"post","link":"https:\/\/dev.sapien.com\/blog\/2011\/06\/01\/primalforms-2011-spotlight-on-controls\/","title":{"rendered":"Spotlight on Controls: Common Properties and Methods"},"content":{"rendered":"<p>The <em><a href=\"https:\/\/www.sapien.com\/blog\/topics\/spotlight-on-controls\/\">Spotlight on Controls<\/a><\/em> series is designed to teach beginning GUI developers about <em>controls<\/em>, the WinForms (System.Windows.Forms) objects that you use in a GUI application.<\/p>\n<p>Each article feature a different WinForms control and introduces its most frequently used properties, methods, and events. Unlike the MSDN reference pages, the examples are written in Windows PowerShell, so you can use them in your scripts.<\/p>\n<p>This post introduces properties that are common to many WinForms controls.<\/p>\n<p><strong>Common\u00a0Properties<\/strong><\/p>\n<ul>\n<li><a href=\"#Name\">Name<\/a><\/li>\n<li><a href=\"#Text\">Text<\/a><\/li>\n<li><a href=\"#Enabled\">Enabled<\/a><\/li>\n<li><a href=\"#Visible\">Visible<\/a><\/li>\n<li><a href=\"#Dock\">Dock<\/a><\/li>\n<li><a href=\"#Anchor\">Anchor<\/a><\/li>\n<\/ul>\n<p><strong>Common\u00a0Methods<\/strong><\/p>\n<ul>\n<li><a href=\"#Focus\">Focus<\/a><\/li>\n<li><a href=\"#Select\">Select<\/a><\/li>\n<\/ul>\n<hr \/>\n<p><a name=\"Name\"><\/a><br \/>\n&nbsp;<\/p>\n<h1>Name property: Specifies a name for the control<\/h1>\n<p>Use the Name property to assign a meaningful identifier to the control.<\/p>\n<p><b>Value type<\/b>: System.String<br \/>\n<b>Default<\/b>: (None)<\/p>\n<p>As a best practice, the name consists of the control type followed by the control text. For example, $buttonClose identifies the Close button.<\/p>\n<p>PowerShell Studio uses the Name and Text properties to assign a default name to the variable that contains the control object. This feature is effective on the following controls: Form, Button, RadioButton, CheckBox and Label.<\/p>\n<p>Notes:<\/p>\n<ul>\n<li>To disable the automatic naming of controls, click Home, Options, Designed, and then uncheck &#8220;Sync control names with text&#8221;.<\/li>\n<li>When you change the Name property of a control in the designer, PowerShell Studio automatically renames the variable that represents the control in your script.<\/li>\n<\/ul>\n<p>Name property in Property Pane:<\/p>\n<p style=\"padding-left: 30px;\"><a href=\"http:\/\/www.sapien.com\/blog\/wp-content\/uploads\/2011\/05\/NameInPropertyPane9.png\"><img loading=\"lazy\" decoding=\"async\" style=\"background-image: none; margin: 0px; padding-left: 0px; padding-right: 0px; display: inline; padding-top: 0px; border: 0px;\" title=\"NameInPropertyPane9\" src=\"http:\/\/www.sapien.com\/blog\/wp-content\/uploads\/2011\/05\/NameInPropertyPane9_thumb.png\" alt=\"NameInPropertyPane9\" width=\"274\" height=\"57\" border=\"0\" \/><\/a><\/p>\n<p>Name variable in Script Editor:<\/p>\n<p style=\"padding-left: 30px;\"><a href=\"http:\/\/www.sapien.com\/blog\/wp-content\/uploads\/2011\/05\/NameInEditor5.png\"><img loading=\"lazy\" decoding=\"async\" style=\"background-image: none; padding-left: 0px; padding-right: 0px; display: inline; padding-top: 0px; border: 0px;\" title=\"NameInEditor5\" src=\"http:\/\/www.sapien.com\/blog\/wp-content\/uploads\/2011\/05\/NameInEditor5_thumb.png\" alt=\"NameInEditor5\" width=\"290\" height=\"103\" border=\"0\" \/><\/a><\/p>\n<p><a name=\"Text\"><\/a><br \/>\n&nbsp;<\/p>\n<h1>Text property: Specifies the text displayed in the control<\/h1>\n<p>Use the Text property to change text in a control. For example, use the Text property to change the title of a Form or the text on a button, label or textbox.<\/p>\n<p><b>Value type<\/b>: System.String<br \/>\n<b>Default<\/b>: (None)<\/p>\n<p>You can also use the Text property to get, set, and change the Text property value. For example, this statement displays a string in a Textbox.<\/p>\n<pre lang=\"PowerShell\">$textbox.Text = \"This is the text in my Textbox\"<\/pre>\n<p><a name=\"Enabled\"><\/a><br \/>\n&nbsp;<\/p>\n<h1>Enabled property: Enables and disables a control<\/h1>\n<p>Use the Enabled property to temporarily enable or disable the default event of the control. For example, when a button is disabled, the user cannot click it. GUI designers often disable controls until the user has provided the input required by the command that the control runs.<\/p>\n<p><b>Value type<\/b>: Boolean ($True, $False)<br \/>\n<b>Default<\/b>: $False<\/p>\n<p>For example, the following statements disable a Start button and re-enable it only when the user enters (non-space) text in the textbox.<\/p>\n<pre lang=\"PowerShell\">$buttonStart = $false\r\nif ($Textbox.Text.Trim() -ne '')\r\n{\r\n    $buttonStart = $true\r\n}<\/pre>\n<p><a name=\"Visible\"><\/a><br \/>\n&nbsp;<\/p>\n<h1>Visible property: Determines whether the control is visible or hidden.<\/h1>\n<p>Use the Visible property to hide controls. Typically, you can hide controls that a user doesn\u2019t need to to see or interact with. A good use for this property is to temporarily display a progress bar.<\/p>\n<p><b>Value type<\/b>: Boolean ($True \/ $False)<br \/>\n<b>Default<\/b>: $True<\/p>\n<p>For example, this code makes a label visible when a user clicks a button.<\/p>\n<pre lang=\"PowerShell\">$buttonDetail_Click = {\r\n    $LabelDetail.Visible = $true\r\n}<\/pre>\n<p><a name=\"Dock\"><\/a><br \/>\n&nbsp;<\/p>\n<h1>Dock property: Attaches a control to a border of a container<\/h1>\n<p>Use the Dock property to attach a control to the side of the parent container or make a control fill the parent container. Containers can be Forms, Panels, or Group Boxes.<\/p>\n<p><b>Value type<\/b>: <a href=\"https:\/\/msdn.microsoft.com\/en-us\/library\/system.windows.forms.dockstyle(v=vs.110).aspx\">System.Windows.Forms.DockStyle<\/a> enumeration (Left, Top, Right, Bottom, Fill, None)<br \/>\n<b>Default<\/b>: None (not docked)<\/p>\n<p>To set the value of the Dock property, use the Properties pane in PowerShell Studio. On the Dock row, use the Dock setting selector.<\/p>\n<p style=\"padding-left: 30px;\"><img loading=\"lazy\" decoding=\"async\" style=\"background-image: none; padding-left: 0px; padding-right: 0px; display: inline; padding-top: 0px; border-width: 0px;\" title=\"Dock Select\" src=\"http:\/\/www.sapien.com\/blog\/wp-content\/uploads\/2011\/05\/Dock-Select.png\" alt=\"Dock Select\" width=\"179\" height=\"207\" border=\"0\" \/><\/p>\n<p>For example, this image shows a button docked to the top of a form.<\/p>\n<p style=\"padding-left: 30px;\"><img loading=\"lazy\" decoding=\"async\" style=\"background-image: none; padding-left: 0px; padding-right: 0px; display: inline; padding-top: 0px; border-width: 0px;\" title=\"Docked Top\" src=\"http:\/\/www.sapien.com\/blog\/wp-content\/uploads\/2011\/05\/Docked-Top1.png\" alt=\"Docked Top\" width=\"200\" height=\"136\" border=\"0\" \/><\/p>\n<p>This image shows a label with a Dock value of Fill.<\/p>\n<p style=\"padding-left: 30px;\"><img loading=\"lazy\" decoding=\"async\" style=\"background-image: none; padding-left: 0px; padding-right: 0px; display: inline; padding-top: 0px; border-width: 0px;\" title=\"Docked Fill\" src=\"http:\/\/www.sapien.com\/blog\/wp-content\/uploads\/2011\/05\/Docked-Fill1.png\" alt=\"Docked Fill\" width=\"196\" height=\"148\" border=\"0\" \/><\/p>\n<p><a name=\"Anchor\"><\/a><br \/>\n&nbsp;<\/p>\n<h1>Anchor property: Binds a control to the edges of a container<\/h1>\n<p>When a control is anchored to an edge, the distance between the control&#8217;s closest edge and the specified edge remains constant. Use the anchor property to move or size a control when the parent control is moved or resized.<\/p>\n<p>The anchor property prevents a control from floating inappropriately. Typically, controls are not anchored only when the parent container is a fixed size.<\/p>\n<p><b>Value type<\/b>: System.Windows.Forms.AnchorStyle enumeration (None, Top, Left, Right, Bottom)<br \/>\n<b>Default<\/b>: Top, Left<\/p>\n<p>To set the Anchor property of a control, use the Property pane in PowerShell Studio. On the Anchor row, use the Anchor selector.<\/p>\n<p style=\"padding-left: 30px;\"><img loading=\"lazy\" decoding=\"async\" style=\"background-image: none; padding-left: 0px; padding-right: 0px; display: inline; padding-top: 0px; border-width: 0px;\" title=\"Anchor Select\" src=\"http:\/\/www.sapien.com\/blog\/wp-content\/uploads\/2011\/05\/Anchor-Select.png\" alt=\"Anchor Select\" width=\"177\" height=\"153\" border=\"0\" \/><\/p>\n<p>For example, the OK button in this form has default Anchor\u00a0values, Top and\u00a0Left<\/p>\n<p style=\"padding-left: 30px;\"><img loading=\"lazy\" decoding=\"async\" style=\"background-image: none; padding-left: 0px; padding-right: 0px; display: inline; padding-top: 0px; border-width: 0px;\" title=\"Original Form\" src=\"http:\/\/www.sapien.com\/blog\/wp-content\/uploads\/2011\/05\/Original-Form.png\" alt=\"Original Form\" width=\"215\" height=\"129\" border=\"0\" \/><\/p>\n<p>When a user drags the lower right corner of the form outward, the button appears to float inappropriately. In fact, it remains anchored to the top left corner.<\/p>\n<p style=\"padding-left: 30px;\"><img loading=\"lazy\" decoding=\"async\" style=\"background-image: none; padding-left: 0px; padding-right: 0px; display: inline; padding-top: 0px; border-width: 0px;\" title=\"Resized Form default Anchor\" src=\"http:\/\/www.sapien.com\/blog\/wp-content\/uploads\/2011\/05\/Resized-Form-without-Anchor.png\" alt=\"Resized Form default Anchor\" width=\"333\" height=\"183\" border=\"0\" \/><\/p>\n<p>In this image, the\u00a0Anchor value is Bottom, Right. Now, when the user resizes the form, the button\u00a0remains\u00a0in the bottom right corner\u00a0with its original offsets.<\/p>\n<p style=\"padding-left: 30px;\"><img loading=\"lazy\" decoding=\"async\" style=\"background-image: none; padding-left: 0px; padding-right: 0px; display: inline; padding-top: 0px; border-width: 0px;\" title=\"Resized Form with Anchor\" src=\"http:\/\/www.sapien.com\/blog\/wp-content\/uploads\/2011\/05\/Resized-Form-with-Anchor.png\" alt=\"Resized Form with Anchor\" width=\"364\" height=\"217\" border=\"0\" \/><\/p>\n<p>&nbsp;<\/p>\n<p>In this example, the Anchor property of the Middle button\u00a0is set to Bottom.<\/p>\n<p style=\"padding-left: 30px;\"><img loading=\"lazy\" decoding=\"async\" style=\"background-image: none; padding-left: 0px; padding-right: 0px; display: inline; padding-top: 0px; border-width: 0px;\" title=\"Original Middle\" src=\"http:\/\/www.sapien.com\/blog\/wp-content\/uploads\/2011\/05\/Original-Middle.png\" alt=\"Original Middle\" width=\"317\" height=\"129\" border=\"0\" \/><\/p>\n<p>When you expand the form, the Middle\u00a0button remains in its position at the bottom center of the form.<\/p>\n<p style=\"padding-left: 30px;\"><img loading=\"lazy\" decoding=\"async\" style=\"background-image: none; padding-left: 0px; padding-right: 0px; display: inline; padding-top: 0px; border-width: 0px;\" title=\"Resized Middle\" src=\"http:\/\/www.sapien.com\/blog\/wp-content\/uploads\/2011\/05\/Resized-Middle.png\" alt=\"Resized Middle\" width=\"493\" height=\"127\" border=\"0\" \/><\/p>\n<p>&nbsp;<\/p>\n<p>In this example,\u00a0the Center button\u00a0is anchored to all sides of a form (Top, Left,\u00a0Bottom, Right) &#8230;<\/p>\n<p style=\"padding-left: 30px;\"><img loading=\"lazy\" decoding=\"async\" style=\"background-image: none; padding-left: 0px; padding-right: 0px; display: inline; padding-top: 0px; border-width: 0px;\" title=\"Original Center\" src=\"http:\/\/www.sapien.com\/blog\/wp-content\/uploads\/2011\/05\/Original-Center.png\" alt=\"Original Center\" width=\"230\" height=\"129\" border=\"0\" \/><\/p>\n<p>When a user enlarges the form, the button expands because the control maintains the same distance from every\u00a0anchored side.\u00a0When anchored to all sides, the\u00a0control is resized whenever the form is resized.<\/p>\n<p style=\"padding-left: 30px;\"><img loading=\"lazy\" decoding=\"async\" style=\"background-image: none; padding-left: 0px; padding-right: 0px; display: inline; padding-top: 0px; border-width: 0px;\" title=\"Resized Center with Anchor set on all sides\" src=\"http:\/\/www.sapien.com\/blog\/wp-content\/uploads\/2011\/05\/Resized-Center-with-All-Anchors.png\" alt=\"Resized Center with Anchor set on all sides\" width=\"319\" height=\"199\" border=\"0\" \/><\/p>\n<p>&nbsp;<\/p>\n<p>To keep a control centered, set the value of the Anchor property to None. Now, when\u00a0the form is resized, the button\u00a0stays at the center and maintains its size.<\/p>\n<p style=\"padding-left: 30px;\"><img loading=\"lazy\" decoding=\"async\" style=\"background-image: none; padding-left: 0px; padding-right: 0px; display: inline; padding-top: 0px; border-width: 0px;\" title=\"Resized Center with no Anchor set\" src=\"http:\/\/www.sapien.com\/blog\/wp-content\/uploads\/2011\/05\/Resized-Center-with-No-Anchors.png\" alt=\"Resized Center with no Anchor set\" width=\"332\" height=\"171\" border=\"0\" \/><\/p>\n<p><a name=\"Focus\"><\/a><br \/>\n&nbsp;<\/p>\n<h1><strong>Focus method: <\/strong>Makes the control active and ready for input<\/h1>\n<p>Use the Focus method to select a control. For example, when you call the Focus method on a TextBox, the Textbox becomes active so that user can begin typing in it without clicking on the TextBox.<\/p>\n<p>The Focus method might be affected by the tab order and other properties of the form. If Focus doesn&#8217;t seem to work, try the Select method.<\/p>\n<p><a name=\"Select\"><\/a><br \/>\n&nbsp;<\/p>\n<h1><strong>Select method: <\/strong>Activates a control<\/h1>\n<p>Use the Select method to activate a control. For example, when you call the Select method on a TextBox, the Textbox becomes active so that user can begin typing in it without clicking on the TextBox. <\/p>\n<p>For example, the following statement in the Load event handler for the Form activates the first textbox so the user can begin typing in it.<\/p>\n<pre lang=\"PowerShell\">$FormRunScript_Load = {\r\n    $TextboxUserName.Select()\r\n}<\/pre>\n<p>You can also use the Select method to switch from one object to another object. For example, when a Textbox object is activated or has focus, a blinking cursor appears in the Textbox, even when the value of the ReadOnly property of the Textbox is True. To avoid the blinking cursor, use a Label instead of a Textbox, or use the Select property to activate a different object on the form, such as a button. <\/p>\n<pre lang=\"PowerShell\">$FormRunScript_Load = {\r\n    $ButtonStart.Select()\r\n}<\/pre>\n<hr>\n<p>Want to learn to about other PowerShell GUI application controls? See the posts in our <em><a href=\"https:\/\/www.sapien.com\/blog\/topics\/spotlight-on-controls\/\">Spotlight on Controls<\/a><\/em> series.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>The Spotlight on Controls series is designed to teach beginning GUI developers about controls, the WinForms (System.Windows.Forms) objects that you use in a GUI application. Each article feature a different WinForms control and introduces its most frequently used properties, methods, and events. Unlike the MSDN reference pages, the examples are written in Windows PowerShell, so [&hellip;]<\/p>\n","protected":false},"author":10,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_monsterinsights_skip_tracking":false,"_monsterinsights_sitenote_active":false,"_monsterinsights_sitenote_note":"","_monsterinsights_sitenote_category":0,"footnotes":""},"categories":[283,575,644,25],"tags":[641,28,633,312],"class_list":["post-2919","post","type-post","status-publish","format-standard","hentry","category-howto","category-primalforms-2011-software-news","category-spotlight-on-controls","category-windows-powershell","tag-controls","tag-powershell","tag-primalforms-2011","tag-winforms"],"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/2919","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/users\/10"}],"replies":[{"embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/comments?post=2919"}],"version-history":[{"count":29,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/2919\/revisions"}],"predecessor-version":[{"id":12087,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/2919\/revisions\/12087"}],"wp:attachment":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/media?parent=2919"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/categories?post=2919"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/tags?post=2919"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}