{"id":6471,"date":"2013-08-14T07:53:00","date_gmt":"2013-08-14T15:53:00","guid":{"rendered":"http:\/\/www.sapien.com\/blog\/?p=6471"},"modified":"2013-08-14T07:54:10","modified_gmt":"2013-08-14T15:54:10","slug":"new-control-set-textbox-watermark","status":"publish","type":"post","link":"https:\/\/dev.sapien.com\/blog\/2013\/08\/14\/new-control-set-textbox-watermark\/","title":{"rendered":"New Control Set: TextBox – Watermark"},"content":{"rendered":"

Recently in the forums we had a request on how to create a textbox with a watermark. <\/p>\n

What is a textbox with a watermark you ask?<\/em> <\/p>\n

It is a textbox that displays hint information within the textbox using a lighter color. For example, a textbox that accepts a username, may have a watermark as follows: <\/p>\n

\"image\" <\/p>\n

Once a user types in the textbox, the watermark goes away. <\/p>\n

\"image\" <\/p>\n

Typically a C# developer would create this control by creating a new class that inherits the original textbox control. Next they would override some paint events and add custom members to keep track of the watermark. Since PowerShell does not support classes natively, this is not so easily done. Thankfully by taking advantage of the textbox control\u2019s events we can mimic the watermark behavior in our PowerShell GUIs. We can also take advantage of PowerShell Studio\u2019s control sets that allows us to drag and drop the new control in the designer instead of having to recreate the event block\u2019s scripts every time. <\/p>\n

Now let\u2019s get started on creating our \u201cnew\u201d control. <\/p>\n

 <\/p>\n

Step 1: Creating the initial watermark effect<\/strong><\/p>\n

In order to mimic the watermark, we will have to change the color of the text and display the watermark message. To do this, we will change the ForeColor of the textbox and use the Text property to display the hint message. <\/p>\n

For this control we set the ForeColor to \u2018LightGray\u2019 when displaying the watermark text: <\/p>\n

$WatermarkText<\/span> <\/span>=<\/span> <\/span>'Please enter your username here'<\/span>\n<\/span>$textBoxWatermark<\/span>.ForeColor <\/span>=<\/span> <\/span>'LightGray'<\/span>\n<\/span>$textBoxWatermark<\/span>.Text <\/span>=<\/span> <\/span>$WatermarkText<\/span>\n<\/span><\/pre>\n
 <\/p>\n
Step 2: Hiding the watermark<\/strong><\/p>\n
Next, we need to clear the watermark as soon as the user places the cursor in the textbox control. We can use the control\u2019s Enter event to accomplish this goal. This event is called whenever the control gains the focus (i.e., The user clicks on the control).<\/p>\n
$textboxWatermark_Enter<\/span>=<\/span>{\n    <\/span>if<\/span>(<\/span>$textboxWatermark<\/span>.Text <\/span>-eq<\/span> <\/span>$WatermarkText<\/span><\/span>)\n    {\n        <\/span>#Clear the text<\/span>\n        <\/span>$textboxWatermark<\/span>.Text <\/span>=<\/span> <\/span>\"\"<\/span>\n        <\/span>$textboxWatermark<\/span>.ForeColor <\/span>=<\/span> <\/span>'WindowText'<\/span>\n    }\n}<\/span><\/pre>\n
In the Enter event we must make sure that we only clear the text property if the control is displaying the watermark text. We also need to change the color of the TextBox back to its default value \u2018WindowText\u2019. <\/p>\n
 <\/p>\n
Step 3: Redisplaying the watermark<\/strong><\/p>\n
When the user goes to another field \/ control, we will need to check if the textbox is empty or not. If it is empty, then the control should display the watermark otherwise it should leave the user\u2019s input as is. In order to do this, we need to use the TextBox\u2019s Leave event. This event is called whenever the control loses the focus.<\/p>\n
$textboxWatermark_Leave<\/span>=<\/span>{\n    <\/span>if<\/span>(<\/span>$textboxWatermark<\/span>.Text <\/span>-eq<\/span> <\/span>\"\"<\/span>)\n    {\n        <\/span>#Display the watermark<\/span>\n        <\/span>$textboxWatermark<\/span>.Text <\/span>=<\/span> <\/span>$WatermarkText<\/span>\n        <\/span>$textboxWatermark<\/span>.ForeColor <\/span>=<\/span> <\/span>'LightGray'<\/span>\n    }\n}<\/span><\/pre>\n
In the Leave event we set the control\u2019s Text property to the watermark text and change the color to Light Gray, only if the user left the control empty. <\/p>\n
 <\/p>\n
Step 4: Create the control set<\/strong><\/p>\n
Now that we have a functional watermark textbox let\u2019s convert it into a control set. Before we do, let\u2019s make the control more self-contained so that it is easier for the user to use multiple instances of this control set. <\/p>\n
First, we don\u2019t want the user to have to manually edit $WatermarkText variable every time they insert the control set. Instead we will use the textbox\u2019s initial value as the watermark and store it in the Tag property (See related articles section for more information on the Tag property). In order to initialize the control automatically, we will use the textbox\u2019s VisibleChanged event. The VisibleChanged event is triggered whenever the control is displayed or hidden. <\/p>\n
$textboxWatermark_VisibleChanged<\/span>=<\/span>{\n    <\/span>if<\/span>(<\/span>$textboxWatermark<\/span>.Visible <\/span>-and<\/span> <\/span>$textboxWatermark<\/span>.Tag <\/span>-eq<\/span> <\/span>$null<\/span>)\n    {\n        <\/span>#Initialize the watermark and save it in the Tag property<\/span>\n        <\/span>$textboxWatermark<\/span>.Tag <\/span>=<\/span> <\/span>$textboxWatermark<\/span>.Text;\n        <\/span>$textboxWatermark<\/span>.ForeColor <\/span>=<\/span> <\/span>'LightGray'<\/span>\n        <\/span>#If we have focus then clear out the text<\/span>\n        <\/span>if<\/span>(<\/span>$textboxWatermark<\/span>.Focused)\n        {\n            <\/span>$textboxWatermark<\/span>.Text <\/span>=<\/span> <\/span>\"\"<\/span>\n            <\/span>$textboxWatermark<\/span>.ForeColor <\/span>=<\/span> <\/span>'WindowText'<\/span>\n        }\n    }\n}\n<\/span><\/pre>\n
The script above checks whether the control is already initialized when it is displayed. If it\u2019s not, the script stores the textbox\u2019s initial text as the watermark text in the Tag property. Next, it checks if the control has the focus. If the control already has the focus, it simply clears the text. <\/p>\n
Next, we update the Enter and Leave events to use the Tag property instead: <\/p>\n
$textboxWatermark_Enter<\/span>=<\/span>{\n    <\/span>if<\/span>(<\/span>$textboxWatermark<\/span>.Text <\/span>-eq<\/span> <\/span>$textboxWatermark<\/span>.Tag)\n    {\n        <\/span>#Clear the text<\/span>\n        <\/span>$textboxWatermark<\/span>.Text <\/span>=<\/span> <\/span>\"\"<\/span>\n        <\/span>$textboxWatermark<\/span>.ForeColor <\/span>=<\/span> <\/span>'WindowText'<\/span>\n    }\n}\n\n<\/span>$textboxWatermark_Leave<\/span>=<\/span>{\n    <\/span>if<\/span>(<\/span>$textboxWatermark<\/span>.Text <\/span>-eq<\/span> <\/span>\"\"<\/span>)\n    {\n        <\/span>#Display the watermark<\/span>\n        <\/span>$textboxWatermark<\/span>.Text <\/span>=<\/span> <\/span>$textboxWatermark<\/span>.Tag\n        <\/span>$textboxWatermark<\/span>.ForeColor <\/span>=<\/span> <\/span>'LightGray'<\/span>\n    }\n}<\/span><\/pre>\n
After we select the watermark textbox in the designer and create our new control set; we are ready to go! <\/p>\n
\"Create<\/a> <\/p>\n
When you insert the \u201cTextBox \u2013 Watermark\u201d control set, you only need to change the control\u2019s Text property in the designer. <\/p>\n
\"Edit<\/a> <\/p>\n
And the resulting text is then displayed as the watermark: <\/p>\n
\"TextBox-Watermark <\/p>\n
 <\/p>\n
Important consideration:<\/strong><\/p>\n
When checking the final value of the TextBox control, you must be sure that it is not equal to the watermark text before accepting the value:<\/p>\n
    <\/span>if<\/span>(<\/span>$textboxWatermark<\/span>.Text <\/span>-eq<\/span> <\/span>$textboxWatermark<\/span>.Tag)\n    {\n        <\/span>#ignore or invalid input    <\/span>\n    }<\/span><\/pre>\n
 <\/p>\n
The \u201cTextBox \u2013 Watermark\u201d control set is available in the v3.1.22 service build of PowerShell Studio 2012.<\/p>\n
 <\/p>\n
Related Links:<\/strong><\/p>\n
The Versatile Tag Property<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"
Recently in the forums we had a request on how to create a textbox with a watermark. What is a textbox with a watermark you ask? It is a textbox that displays hint information within the textbox using a lighter color. For example, a textbox that accepts a username, may have a watermark as follows: […]<\/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":[705,644,25],"tags":[712,28,1016,654,837],"class_list":["post-6471","post","type-post","status-publish","format-standard","hentry","category-powershell-studio-2012","category-spotlight-on-controls","category-windows-powershell","tag-control-sets","tag-powershell","tag-powershell-studio","tag-textbox","tag-watermark"],"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/6471","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=6471"}],"version-history":[{"count":4,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/6471\/revisions"}],"predecessor-version":[{"id":6483,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/6471\/revisions\/6483"}],"wp:attachment":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/media?parent=6471"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/categories?post=6471"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/tags?post=6471"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
Spotlight on the TextBox Control<\/a><\/p>\n