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.

Layout and management of subwidgets/frames similar to an IDE.
Resizable panes. Separate frames/widgets in the top-level window can be resized by dragging the separator border between the frames.
Support for Tabbed-Frames (using of subclass of Tk::DynaTabFrame, where each tab can be dragged/dropped; to another tabframe in the IDE, or to a new separate window, or to "edge" ares in the mainwindow to create new tabframes.

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 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.

toolbar

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

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 Tk::IDEtabFrame options to be used when creating new Tk::IDEtabFrame widgets.

New Tk::IDEtabFrame Widgets are created when something is dragged/dropped to an interior/exterior edge of the Tk::IDElayout Widget. This array ref will be used to create the new Tk::IDEtabFrame 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',
]

IDEpanedwindowConfig

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

New Tk::IDEpanedwindow Widgets are created when something is dragged/dropped to an interior/exterior edge of the Tk::IDElayout 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 Tk::IDEpanedwindow 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 Graph::Directed structure.

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.

panedWindow nodes represent Tk::IDEpanedWindow widgets that manage one or more subwidgets.

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

name

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

dir

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

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

childOrder

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

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

expandfactors

List of expandFactors for the frames managed by the Tk::IDEpanedwindow 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 Tk::IDEpanedwindow 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.

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 Graph::Directed object in the 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: Tk::Frame object that holds the menu bar at the top of the main window.
mainPW: Tk::IDEanedWindow object used for main display of widgets.
toolbarFrame: Tk::Frame object that holds the toolbar (if used).
statusLineFrame: Tk::Frame object that holds the status-line widget.

ATTRIBUTES

indicator: Tk::Frame 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.
currentFrame: Current frame that the mouse pointer is over during a drag/drop operation.
currentSide: Current side of the frame (e.g. left, right, top, bot) that the mouse pointer is over during a drag/drop operation.
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 Tk::IDElayout

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 Tk::GraphVizViewer.

Requires the Tk::GraphVizViewer 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 Tk::IDEtabFrame widget to hold the dragged widget.

defaultIDEtabFrameConfig

Cleas method that returns the default Tk::IDEtabFrame 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 Tk::IDEtabFrame 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()

To install Tk::IDElayout, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Tk::IDElayout

CPAN shell

perl -MCPAN -e shell
install Tk::IDElayout

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

FrameStructure Description

Node Entry

Edges Entry

Example Structure

Advertised Sub-widgets

ATTRIBUTES

Methods

findFrame

findSide

flashSide

addWidgetAtSide

_createNewPWname()

deleteWidget

simplifyAfterDelete

displayStruct

Drop

defaultIDEtabFrameConfig

adjustGeom

Module Install Instructions