Tk::IDElayout - Tk Widget for Layout of Frames Similar to an IDE.


NAME

Tk::IDElayout - Tk Widget for Layout of Frames Similar to an IDE.


SYNOPSIS

Simple Example: (See t/simpleIDElayout2.t in the source distrubution for complete example)

        #### This example creates two IDEtabFrames for managing with IDElayout #####
        my $TOP = MainWindow->new;
        
        ###  Create layout structures ###
        ###    This structure has the PaneWindow (P1) at the top level, 
        ###      and the two IDEtabFrames next lower level.
        ###     Graphically, this looks like this:
        ###     +------+     +------+
        ###     |  P1  | ==> | Tab1 |
        ###     +------+     +------+
        ###       H
        ###       H
        ###       v
        ###     +------+
        ###     | Tab2 |
        ###     +------+
        my @nodes = (
          {  name => 'P1', 
           dir  => 'V',
           childOrder => ['Tab1', 'Tab2'],
           type => 'panedWindow',
          },  
           {  name => "Tab1", type => 'widget'
           },
           {  name => "Tab2", type => 'widget'
           }
        );
        my @edges = (
           [ 'P1', 'Tab1'],
           [ 'P1', 'Tab2'],
           );
        
        
        #################### Create Widgets ##################################
        # We will use the same default IDEtabFrame config that the IDElayout widget uses
        my $IDEtabFrameConfig = Tk::IDElayout->defaultIDEtabFrameConfig();
        
        ###  TabFrame 1 ###
        my $dtf = $TOP->IDEtabFrame( @$IDEtabFrameConfig);      
        $dtf->configure(-height => 400);
        
        
        ###  TabFrame 2 ###     
        my $dtf2 = $TOP->IDEtabFrame( @$IDEtabFrameConfig);
         
        ######### Populate widgets hash with the two TabFrames created ######
        my %widgets = ( 'Tab1' => $dtf,
                        'Tab2' => $dtf2,
                        );
        
        
        # Create simple menubar
        my $MenuBar = $TOP->Frame(-class => 'Menubar'); # We don't pack this, it will be packed by IDElayout
       
        
        # Create simple statusLine
        my $statusText = "This is statusLine Text";
        my $statusLine = $TOP->Label(-textvariable => \$statusText, -anchor => 'w');
        
        
        # Structure Created, now buld the Tk::IDElayout
        
        my $layout = $TOP->IDElayout(
                -widgets => \%widgets,
                -frameStructure => { nodes => \@nodes,  edges => \@edges},
                -menu    => $MenuBar,
                -statusLine => $statusLine,
                );
        
        
        $layout->pack(-side => 'top', -fill => 'both', -expand => 'yes');


DESCRIPTION

This is a widget for managing the layout of Tk frames (and other widgets) like an IDE (Integrated Development Environment) like Ecliplse or Microsoft Visual Studio.

Features:

See Screenshots.pdf in the source distribution for some screenshots demonstrating some of these features.


OPTIONS

frameStructure
Hash ref representing the structure and layout of the frames managed by this widget. See FrameStructure Description below for details on this structure.

This option, or I<frameGraph> below is required to be supplied to the widget when it is created.

frameGraph
Graph object representing the frame structure, built from the above frameStructure. This is used internally by the object for manipulation of the frame structures. Normally this is built from the frameStructure data above, but can be directly supplied by setting this option.

This option, or frameStructure above is required to be supplied to the widget when it is created.

widgets
Hashref (key-ed by name) of subwidgets managed by this widget.

menu
Required menu widget that will displayed at the top of the top-level window.

=item toolbar

Optional the Tk::ToolBar manpage widget to display below the menu above.


=item statusLine

Optional status-line frame to display at the bottom of the top-level window. A status-line is typically used to display short top-level status items to the user.

IDEtabFrameConfig
Optional array ref of the Tk::IDEtabFrame manpage options to be used when creating new the Tk::IDEtabFrame manpage widgets.

New the Tk::IDEtabFrame manpage Widgets are created when something is dragged/dropped to an interior/exterior edge of the the Tk::IDElayout manpage Widget. This array ref will be used to create the new the Tk::IDEtabFrame manpage widgets.

If not supplied, this defaults to:

 [
        -tabclose => 1,
        -tabcolor => 'white',
        -raisecolor => 'grey90',
        -tabpady => 1,
        -tabpadx => 1,
        -padx => 0,
        -pady => 0,
        -bg => 'white',
        -raisedfg => 'black',                        
        -raisedCloseButtonfg => 'black',
        -raisedCloseButtonbg => 'lightgrey',
        -raisedCloseButtonActivefg => 'red',
        -noraisedfg => 'grey60',
        -noraisedActivefg => 'black',
        -noraisedCloseButtonfg => 'lightgrey',
        -noraisedCloseButtonbg => 'white',
        -noraisedCloseButtonActivefg => 'red',
 ]
 
=item IDEpanedwindowConfig

Optional array ref of the Tk::IDEpanedwindow manpage options to be used when creating new the Tk::IDEpanedwindow manpage widgets.

New the Tk::IDEpanedwindow manpage Widgets are created when something is dragged/dropped to an interior/exterior edge of the the Tk::IDElayout manpage Widget that is not compatible with the existing panedwidnow direction (For example when a widget is dragged/dropped to the top or bottom of a horizontal panewindow). This array ref will be used to create the new the Tk::IDEpanedwindow manpage widgets.

If not supplied, this defaults to:

 [      -sashpad   => 1,
        -sashwidth => 6,
        -sashrelief=> 'ridge'
 ]

ResizeOnReconfig
Flag = 1 if the mainwindow should be resized when the IDElayout structure is reconfigured (i.e. widget added or deleted to the structure, triggerd be a call to the addWidgetAtSide or deleteWidget method. )

If the flag is 1, the top level window will be resized to the requested width/height (obtained thru the reqwidth and reqheight methods) of the window. This can be useful in some situations where the user has resized a window to be large, and then deletes some widgets, resulting in a big window with not much in it. Setting this flag to 1 in this situation will cause the window to shrink to accomodate the requested size of the widgets that are left in the window.

Defaults to 0.


FrameStructure Description

The structure of the frames managed by this widget is defined by the frameStructure option. This is a hash ref with two entries, nodes and edges, which together describe a the Graph::Directed manpage structure.


=head2 Node Entry

The node entry is an array ref containing descriptions for each node/frame managed by the widget. Each node entry is a hash ref with the following entries:

type
Node Type. Valid entries are panedWindow or widget.

I<panedWindow> nodes represent L<Tk::IDEpanedWindow> widgets that manage one or more subwidgets.

widget nodes represent normal Tk widgets that are managed by a the Tk::IDEpanedWindow manpage widget.

name
Name of the node. If type above is 'widget', this should correspond to a entry in the widgets option.

=item dir

Direction (H/V for Horizontal/Vertical) of the the Tk::IDEpanedWindow manpage panes. Only applies for the panedWindow type.

Horizontal/Verical (H/C) indicates the direction the frames of the the Tk::IDEpanedwindow manpage widget are oriented.

childOrder
Order of the frames managed by the the Tk::IDEpanedWindow manpage widget. Only applies for the panedWindow type.

This is a list of widget names managed by the the Tk::IDEpanedwindow manpage widget.

expandfactors
List of expandFactors for the frames managed by the the Tk::IDEpanedwindow manpage widget. Only applies for the panedWindow type.

Expandfactors determine how the individual widget frames expand or shrink when the entire window is resized. See the the Tk::IDEpanedwindow manpage docs for details.

Edges Entry

The edges entry represents the edges (or connections) between the nodes described by the nodes entry. It is a list of 2-element arrays. Each 2-element array represents a connection between nodes.


=head2 Example Structure

The following is an example of a simple frameStructure.


  my $frameStructure  = {
      nodes = [
          {  name => 'P1', 
             dir  => 'H',
             childOrder => ['Frame 1', 'P2']
          },  
          {  name => "Frame 1",
          },
          {  name => 'P2',
             dir  => 'V',
             childOrder => ['Frame 2', 'Frame 3']
          },
          {  name => 'Frame 2' },
          {  name => 'Frame 3' },
         ],
      edges = [
           [ 'P1', 'Frame 1'],
           [ 'P1', 'P2'],
           [ 'P2', 'Frame 2'],
           [ 'P2', 'Frame 3'],
        ]
   };

The above will result in the following frame structure (as a L<Graph::Directed> object in the I<frameGraph> option).

        +--------+     +--------+     +--------+
        |   P1   | --> |   P2   | --> | Frame2 |
        +--------+     +--------+     +--------+
          |              |
          |              |
          v              v
        +--------+     +--------+
        | Frame1 |     | Frame3 |
        +--------+     +--------+

The top-level PanedWindow, P1, manages Frame1 and another PanedWindow, P2, in the horizontal direction

The PanedWindow P2 manages Frame2 and Frame3 in the vertical direction.


The actual layout on the screen will look something like this.

       +---------------+----------------+
       |               |     Frame2     |
       |    Frame1     +----------------|
       |               |     Frame3     |
       |---------------+----------------+


Advertised Sub-widgets

menuFrame
the Tk::Frame manpage object that holds the menu bar at the top of the main window.

mainPW
the Tk::IDEanedWindow manpage object used for main display of widgets.

=item toolbarFrame

the Tk::Frame manpage object that holds the toolbar (if used).

statusLineFrame
the Tk::Frame manpage object that holds the status-line widget.

=back


ATTRIBUTES

indicator
the Tk::Frame manpage object used to indicate drop target areas. This will appear as a horizontal or vertical Bar on the sides or top/bottom of a frame to indicate where a drag/drop operation can be dropped.
        
=item currentFrame

Current frame that the mouse pointer is over during a drag/drop operation.


=item currentSide

Current side of the frame (e.g. left, right, top, bot) that the mouse pointer is over during a drag/drop operation.


=item lastSide

The last side of the frame (e.g. left, right, top, bot) that the mouse pointer was over during a drag/drop operation.


Methods

findFrame

Given the current x/y position, return the frame (if any) (and the bounding box coord) that the x/y position is within

Usage:

   my ($frameName, $x1,$y1, $x2,$y2) = $self->findFrame($x,$y);
   
   returns an empty list if x/y position is not within any frame

findSide

Method to find the side of a frame we are ``close'' to. Used for dragging, where the edges of the IDElayout frames are drop targets.

Usage:

   my $side = $self->findSide($pointerx,$pointery, $frameName,
                  $x1, y1, $x2, $y2);
     where: $pointerx   x coord of the current pointer
            $pointery   y coord of the current pointer
            $frameName  Name of frame
            $x1/y1/x2/y2 Frame Coords
            
    Returns $side (top/bot/left/right) if we
    are close to a side.

flashSide

Flash the drop indicator at a side of a frame.

Usage:

  $self->flashSide($side, $frame);
   where: 
     $side: Name of side (e.g. top/bot/left/right)
     $frame: Name of frame (as it appears in the frameList

addWidgetAtSide

Method to add a widget to the Panedwindow arrangement at the frame side.

Usage:

   $self->addWidgetAtSide($widget, $widgetName, $currentFrame, $currentSide, $attr);
        where: 
          $widget:       Widget to add.
          $widgetName:   Name of the widget to add
          $currentFrame: Name of the current frame we are adding to
          $currentSide:  Name of the side of the frame we are adding to (e.g. top/bot/left/right)
          $attr:         Optional hash ref of options for the widget to add
                          (Only -expandfactor supported at this time)

_createNewPWname()

Method create a unique Paned-Window name from the existing Paned-Window widgets being managed by this widget.


For example, if there are Paned-Window P1, P2, P3 being managed, then this method will return P4.

Usage:

   my $newName = $self->_createNewPWname();

deleteWidget

Method to delete a widget from being managed by the Tk::IDElayout manpage

Usage:

   my $widget $self->deleteWidget($widgetName);
        where: 
          $widgetName:   Name of the widget to delete
          $widget:       Widget deleted

simplifyAfterDelete

Sub to simplify the window structure after a delete.

This checks to see if there is a Panewindow with only one element, and if there is, gets rid of it.

Usage:

   $self->simplifyAfterDelete($pwName, $widgetName);
     
   where:
      $pwName:      Parent panedwindow name of the widget just deleted
      $widgetName:  Name of the widget just deleted

displayStruct

Debug-only method to display the structure of the managed widgets as a Directed Graph using GraphViz and the Tk::GraphVizViewer manpage. Requires the the Tk::GraphVizViewer manpage widget.

Usage:

   $self->displayStruct($title);
   
      where: $title: Optional title to give the display window

Drop

Method called when accepting a drop from a drag-drop operation. Creates and populates a new the Tk::IDEtabFrame manpage widget to hold the dragged widget.

defaultIDEtabFrameConfig

Cleas method that returns the default the Tk::IDEtabFrame manpage options that will be used to set the -IDEtabFrameConfig options if not supplied. This is broken out as a class method so the defaults can be used for initial setup of the the Tk::IDEtabFrame manpage widgets for simple example scripts.

Usage:

   my $tabFrameConfig = Tk::IDElayout->defaultIDEtabFrameConfig()

adjustGeom

Method to resize the main window of the GUI to the requested width/height of the window. This is called at the end of the deleteWidget and addWidgetAtSide methods if the ResizeOnReconfig option is 1.

Usage:

   $self->adjustGeom()

 Tk::IDElayout - Tk Widget for Layout of Frames Similar to an IDE.