New SectionBar JavaScript Object

[Juan Conejero]

Hi all,

I have just released an update for PixInsight 1.8.0 RC5 with a new standard PJSR header: SectionBar.jsh. As its name suggests, this header provides the new SectionBar JavaScript object.

SectionBar is a specialized control to manage vertically collapsible/extensible dialog sections. SectionBar provides an optional check box and a title label, in a similar way to GroupBox. SectionBar also includes a special icon that represents the current collapsed/expanded state. Basically, this object is the JavaScript counterpart to the SectionBar C++/PCL class. A number of scripts have been implementing similar controls with variations around an example code I published some time ago, so I have decided to release a standard version of this useful control.


Constructor

new SectionBar( [Control parent[, String title]] )

Creates a new SectionBar control with optional parent control and title.


Methods

Boolean SectionBar.hasCheckBox()

Returns true if the SectionBar has a check box enabled.

Boolean SectionBar.isChecked()

Returns true if the SectionBar has its check box enabled and the check box is checked.

void SectionBar.enableCheckBox()

Creates a CheckBox control at the left side of the title. When the check box is checked/unchecked, the section control is enabled/disabled. Note that the creation of a check box property cannot be undone (there's no disableCheckBox() method).

String SectionBar.title()

Returns the current title shown on the SectionBar control.

void SectionBar.setTitle( String title )

Changes the title shown on the SectionBar control.

Boolean SectionBar.hasSection()

Returns true if the SectionBar has an associated section control. By default, i.e. after a SectionBar is created, it has no associated section control.

void SectionBar.setSection( Control section )

Sets a new section control that will be associated with (and managed by) this SectionBar control.

Boolean SectionBar.isExpanded()

Returns true if the SectionBar is currently in expanded state. When a SectionBar is expanded, its associated section control (if any) is visible.

Boolean SectionBar.isCollapsed()

Returns true if the SectionBar is currently in collapsed state. When a SectionBar is collapsed, its associated section control (if any) is hidden.

void SectionBar.toggleSection()

Inverts the current collapsed/expanded state. You normally should not need to call this method directly, since SectionBar invokes it when appropriate. You can simply show or hide the associated section control directly, as SectionBar intercepts its onShow() and onHide() event handlers.

void SectionBar.updateSection()

Updates the geometry of the parent dialog of this SectionBar control, according to the current collapsed/expanded state. Call this method, if necessary, after manually changing the visible state of the associated section control.


Event Handlers

To improve its flexibility, SectionBar provides also two event handlers:

SectionBar.onToggleSection( Control bar, Boolean toggleBegin )

If this event handler is defined, SectionBar calls it twice when its collapsed/expanded state changes: a first time before changing the collapsed/expanded state with toggleBegin=true, and a second time after changing the state with toggleBegin=false. The bar event argument is the SectionBar control that triggered the toggle section event.

SectionBar.onCheckSection( Control bar )

If this event is defined and the SectionBar control has its check box enabled (after calling SectionBar.enableCheckBox()), it is called when its checked state changes.


Demo Script

The best way to see how SectionBar works in practice, is through a little example script, which I have included below:

Code: [Select]

/*
 * SectionBarTest.js - an example demo script for the SectionBar control.
 */

#include <pjsr/SectionBar.jsh>

function MyDialog()
{
   this.__base__ = Dialog;
   this.__base__();

   this.label = new Label( this );
   this.label.useRichText = true;
   this.label.text = "<p>This is Section #1. If you read this, then this section is expanded.</p>" +
      "<p>Otherwise it is collapsed. If you find this information useful, then you need more coffee :)</p>";

   this.textBox = new TextBox( this );
   this.textBox.text = "<html><p>This is Section #2. If you read this, then this section is expanded.</p>" +
      "<p>Otherwise it is collapsed. If you find this information useful, then you need more coffee :)</p></html>";

   this.info = new Label( this );
   this.info.minWidth = 250;

   this.hSizer = new HorizontalSizer;
   this.hSizer.add( this.info, 100 );

   this.onToggleSection = function( bar, beginToggle )
   {
      if ( beginToggle )
      {
         this.dialog.textBox.setFixedSize();
         this.dialog.setVariableSize();
      }
      else
      {
         this.dialog.textBox.setVariableSize();
         if ( this.dialog.textBox.visible )
            this.dialog.setVariableSize();
         else
            this.dialog.setFixedSize();
         this.dialog.info.text = bar.title() + " has been " + (bar.isExpanded() ? "expanded" : "collapsed");
      }
   };

   this.onCheckSection = function( bar )
   {
      this.dialog.info.text = bar.title() + " has been " + (bar.isChecked() ? "checked" : "unchecked");
   };

   this.section1 = new Control( this );
   this.section1.setMinSize( 300, 200 );
   this.section1.sizer = new VerticalSizer;
   this.section1.sizer.add( this.label );

   this.bar1 = new SectionBar( this, "Section One" );
   this.bar1.setSection( this.section1 );
   this.bar1.enableCheckBox();
   this.bar1.onToggleSection = this.onToggleSection;
   this.bar1.onCheckSection = this.onCheckSection;

   this.section2 = new Control( this );
   this.section2.setMinSize( 300, 200 );
   this.section2.sizer = new VerticalSizer;
   this.section2.sizer.add( this.textBox );

   this.bar2 = new SectionBar( this, "Section Two" );
   this.bar2.setSection( this.section2 );
   this.bar2.onToggleSection = this.onToggleSection;
   this.bar2.onCheckSection = this.onCheckSection;

   this.sizer = new VerticalSizer;
   this.sizer.margin = 8;
   this.sizer.spacing = 4;
   this.sizer.add( this.bar1 );
   this.sizer.add( this.section1 );
   this.sizer.add( this.bar2 );
   this.sizer.add( this.section2 );
   this.sizer.addSpacing( 4 );
   this.sizer.add( this.hSizer );

   this.section1.hide();

   this.adjustToContents();
   this.windowTitle = "SectionBar Test";
   this.width = 600;
};

MyDialog.prototype = new Dialog;

var d = new MyDialog;
d.execute();
As you see, using SectionBar is rather simple: Just declare it as a child of your dialog, and pass a section control by calling the SectionBar.setSection() method. After this call the section control will be managed by the SectionBar object, as you can verify by running the script above.

I urge all PJSR developers to update their scripts, as necessary, using the new standard SectionBar control. Happy coding!

[mschuster]

Thank you Juan, I will update. Much appreciated to have a replacement.
Mike

[Andres.Pozo]

Thanks Juan. It's going to be very useful.