NAME

Padre::Wx::Main - The main window for the Padre IDE

DESCRIPTION

Padre::Wx::Main implements Padre's main window. It is the window containing the menus, the notebook with all opened tabs, the various sub- windows (outline, subs, output, errors, etc).

It inherits from Wx::Frame, so check wx documentation to see all the available methods that can be applied to it besides the added ones (see below).

PUBLIC API

Constructor

There's only one constructor for this class.

new

my $main = Padre::Wx::Main->new( $ide );

Create and return a new Padre main window. One should pass a Padre object as argument, to get a reference to the Padre application.

Accessors

The following methods access the object attributes. They are both getters and setters, depending on whether you provide them with an argument. Use them wisely.

Accessors to GUI elements:

• title()

• config()

• aui()

• menu()

• notebook()

• right()

• functions()

• outline()

• directory()

• bottom()

• output()

• syntax()

• errorlist()

Accessors to operating data:

• cwd()

• no_refresh()

Accessors that may not belong to this class:

• ack()

Public Methods

load_files

$main->load_files;

Load any default files: session from command-line, explicit list on command- line, or last session if user has this setup, a new file, or nothing.

freezer

my $locker = $main->freezer;

Create and return an automatic Freeze object that Thaw's on destruction.

Single Instance Server

Padre embeds a small network server to handle single instance. Here are the methods that allow to control this embedded server.

• $main->single_instance_start;

  Start the embedded server. Create it if it doesn't exist. Return true on success, die otherwise.

• $main->single_instance_stop;

  Stop & destroy the embedded server if it was running. Return true on success.

• my $is_running = $main->single_instance_running;

  Return true if the embedded server is currently running.

• $main->single_instance_connect;

  Callback called when a client is connecting to embedded server. This is the case when user starts a new Padre, and preference "open all documents in single Padre instance" is checked.

• $main->single_instance_command( $line );

  Callback called when a client has issued a command $line while connected on embedded server. Current supported commands are open $file and focus.

Window Methods

Those methods allow to query properties about the main window.

• my $width = $main->window_width;

  Return the main window width.

• my $width = $main->window_height;

  Return the main window height.

• my $left = $main->window_left;

  Return the main window position from the left of the screen.

• my $top = $main->window_top;

  Return the main window position from the top of the screen.

Refresh Methods

Those methods refresh parts of Padre main window. The term refresh and the following methods are reserved for fast, blocking, real-time updates to the GUI, implying rapid changes.

$main->refresh;

Force refresh of all elements of Padre main window. (see below for individual refresh methods)

$main->refresh_syntaxcheck;

Do a refresh of document syntax checking. This is a "rapid" change, since actual syntax check is happening in the background.

$main->refresh_menu;

Force a refresh of all menus. It can enable / disable menu entries depending on current document or Padre internal state.

$main->refresh_menubar;

Force a refresh of Padre's menubar.

$main->refresh_toolbar;

Force a refresh of Padre's toolbar.

$main->refresh_status;

Force a refresh of Padre's status bar.

$main->refresh_functions;

Force a refresh of the function list on the right.

Interface Rebuilding Methods

Those methods reconfigure Padre's main window in case of drastic changes (locale, etc.)

• $main->change_style( $style, $private );

  Apply $style to Padre main window. $private is a boolean true if the style is located in user's private Padre directory.

• $main->change_locale( $locale );

  Change Padre's locale to $locale. This will update the GUI to reflect the new locale.

• $main->relocale;

  The term and method relocale is reserved for functionality intended to run when the application wishes to change locale (and wishes to do so without restarting).

  Note at this point, that the new locale has already been fixed, and this method is usually called by change_locale().

• $main->reconfig( $config );

  The term and method "reconfig" is reserved for functionality intended to run when Padre's underlying configuration is updated by an external actor at run-time. The primary use cases for this method are when the user configuration file is synced from a remote network location.

  Note: This method is highly experimental and subject to change.

• $main->rebuild_toolbar;

  Destroy and rebuild the toolbar. This method is useful because the toolbar is not really flexible, and most of the time it's better to recreate it from scratch.

Panel Tools

Those methods deal with the various panels that Padre provides, and allow to show or hide them.

• $main->show_functions( $visible );

  Show the functions panel on the right if $visible is true. Hide it otherwise. If $visible is not provided, the method defaults to show the panel.

• $main->show_outline( $visible );

  Show the outline panel on the right if $visible is true. Hide it otherwise. If $visible is not provided, the method defaults to show the panel.

• $main->show_directory( $visible );

  Show the directory panel on the right if $visible is true. Hide it otherwise. If $visible is not provided, the method defaults to show the panel.

• $main->show_output( $visible );

  Show the output panel at the bottom if $visible is true. Hide it otherwise. If $visible is not provided, the method defaults to show the panel.

• $main->show_syntax( $visible );

  Show the syntax panel at the bottom if $visible is true. Hide it otherwise. If $visible is not provided, the method defaults to show the panel.

Introspection

The following methods allow to poke into Padre's internals.

• my $current = $main->current;

  Creates a Padre::Current object for the main window, giving you quick and cacheing access to the current various whatevers.

  See Padre::Current for more information.

• my @ids = $main->pageids;

  Return a list of all current tab ids (integers) within the notebook.

• my @pages = $main->pages;

  Return a list of all notebook tabs. Those are the real objects, not the ids (see pageids() above).

• my @editors = $main->editors;

  Return a list of all current editors. Those are the real objects, not the ids (see pageids() above).

  Note: for now, this has the same meaning as pages() (see above), but this will change once we get project tabs or something else.

Process Execution

The following methods run an external command, for example to evaluate current document.

• $main->on_run_command;

  Prompt the user for a command to run, then run it with run_command() (see below).

  Note: it probably needs to be combined with run_command() itself.

• $main->on_run_tests;

  Callback method, to run the project tests and harness them.

• $main->run_command( $command );

  Run $command and display the result in the output panel.

• $main->run_document( $debug )

  Run current document. If $debug is true, document will be run with diagnostics and various debug options.

  Note: this should really be somewhere else, but can stay here for now.

• $main->debug_perl;

  Run current document under perl debugger. An error is reported if current is not a Perl document.

Session Support

Those methods deal with Padre sessions. A session is a set of files / tabs opened, with the position within the files saved, as well as the document that has the focus.

• my @session = $main->capture_session;

  Capture list of opened files, with information. Return a list of Padre::DB::SessionFile objects.

• $main->open_session( $session );

  Try to close all files, then open all files referenced in the given $session (a Padre::DB::Session object). No return value.

• $main->save_session( $session, @session );

  Try to save @session files (Padre::DB::SessionFile objects, such as what is returned by capture_session() - see above) to database, associated to $session. Note that $session should already exist.

User Interaction

Various methods to help send information to user.

• $main->message( $msg, $title );

  Open a dialog box with $msg as main text and $title (title defaults to Message). There's only one OK button. No return value.

• $main->error( $msg );

  Open an error dialog box with $msg as main text. There's only one OK button. No return value.

• my $find = $main->find;

  Returns the find dialog, creating a new one if needed.

• my $find = $main->fast_find;

  Return current quick find dialog. Create a new one if needed.

• my $replace = $main->replace;

  Return current replace dialog. Create a new one if needed.

• my $value = $main->prompt( $title, $subtitle, $key );

  Prompt user with a dialog box about the value that $key should have. Return this value, or undef if user clicked cancel.

General Events

Those methods are the various callbacks registered in the menus or whatever widgets Padre has.

• $main->on_brace_matching;

  Jump to brace matching current the one at current position.

• $main->on_comment_toggle_block;

  Un/comment selected lines, depending on their current state.

• $main->on_comment_out_block;

  Comment out selected lines unilateraly.

• $main->on_uncomment_block;

  Uncomment selected lines unilateraly.

• $main->on_autocompletition;

  Try to autocomplete current word being typed, depending on document type.

• $main->on_goto;

  Prompt user for a line, and jump to this line in current document.

• $main->on_close_window( $event );

  Callback when window is about to be closed. This is our last chance to veto the $event close, eg when some files are not yet saved.

  If close is confirmed, save config to disk. Also, capture current session to be able to restore it next time if user set Padre to open last session on startup. Clean up all Task Manager's tasks.

• $main->on_split_window;

  Open a new editor with the same current document. No return value.

• $main->setup_editors( @files );

  Setup (new) tabs for @files, and update the GUI. If @files is undef, open an empty document.

• $main->on_new;

  Create a new empty tab. No return value.

• $main->setup_editor( $file );

  Setup a new tab / buffer and open $file, then update the GUI. Recycle current buffer if there's only one empty tab currently opened. If $file is already opened, focus on the tab displaying it. Finally, if $file does not exist, create an empty file before opening it.

• my $tab = $main->create_tab;

  Create a new tab in the notebook, and return its id (an integer).

• $main->on_open_selection;

  Try to open current selection in a new tab. Different combinations are tried in order: as full path, as path relative to cwd (where the editor was started), as path to relative to where the current file is, if we are in a perl file or perl environment also try if the thing might be a name of a module and try to open it locally or from @INC.

  No return value.

• $main->on_open_all_recent_files;

  Try to open all recent files within Padre. No return value.

• $main->on_open;

  Prompt user for file(s) to open, and open them as new tabs. No return value.

• $main->on_reload_file;

  Try to reload current file from disk. Display an error if something went wrong. No return value.

• my $was_saved = $main->on_save_as;

  Prompt user for a new filename to save current document, and save it. Returns true if saved, false if cancelled.

• my $success = $main->on_save;

  Try to save current document. Prompt user for a filename if document was new (see on_save_as() above). Return true if document has been saved, false otherwise.

• my $success = $main->on_save_all;

  Try to save all opened documents. Return true if all documents were saved, false otherwise.

• my $success = $main->_save_buffer( $id );

  Try to save buffer in tab $id. This is the method used underneath by all on_save_*() methods. It will check if document has been updated out of Padre before saving, and report an error if something went wrong. Return true if buffer was saved, false otherwise.

• $main->on_close( $event );

  Handler when there is a close $event. Veto it if it's from the aui notebook, since wx will try to close the tab no matter what. Otherwise, close current tab. No return value.

• my $success = $main->close( $id );

  Request to close document in tab $id, or current one if no $id provided. Return true if closed, false otherwise.

• my $success = $main->on_close_all;

  Event called when menu item close all has been hit. Return true if all documents were closed, false otherwise.

• my $success = $main->on_close_all_but_current;

  Event called when menu item close all but current has been hit. Return true upon success, false otherwise.

• my $success = $main->_on_close_all( $skip );

  Try to close all documents. If $skip is specified (an integer), don't close the tab with this id. Return true upon success, false otherwise.

• $main->on_nth_pane( $id );

  Put focus on tab $id in the notebook. Return true upon success, false otherwise.

• $main->on_next_pane;

  Put focus on tab next to current document. Currently, only left to right order is supported, but later on it can be extended to follow a last seen order.

  No return value.

• $main->on_prev_pane;

  Put focus on tab previous to current document. Currently, only right to left order is supported, but later on it can be extended to follow a reverse last seen order.

  No return value.

• $main->on_diff;

  Run Text::Diff between current document and its last saved content on disk. This allow to see what has changed before saving. Display the differences in the output pane.

• $main->on_join_lines;

  Join current line with next one (a-la vi with Ctrl+J). No return value.

Preferences and toggle methods

Those methods allow to change Padre's preferences.

• $main->zoom( $factor );

  Apply zoom $factor to Padre's documents. Factor can be either positive or negative.

• $main->on_preferences;

  Open Padre's preferences dialog. No return value.

• $main->on_toggle_line_numbers;

  Toggle visibility of line numbers on the left of the document. No return value.

• $main->on_toggle_code_folding;

  De/activate code folding. No return value.

• $main->on_toggle_currentline;

  Toggle overlining of current line. No return value.

• $main->on_toggle_syntax_check;

  Toggle visibility of syntax panel. No return value.

• $main->on_toggle_errorlist;

  Toggle visibility of error-list panel. No return value.

• $main->on_toggle_indentation_guide;

  Toggle visibility of indentation guide. No return value.

• $main->on_toggle_eol;

  Toggle visibility of end of line cariage returns. No return value.

• $main->on_toggle_whitespaces;

  Show/hide spaces and tabs (with dots and arrows respectively). No return value.

• $main->on_word_wrap;

  Toggle word wrapping for current document. No return value.

• $main->on_toggle_toolbar;

  Toggle toolbar visibility. No return value.

• $main->on_toggle_statusbar;

  Toggle statusbar visibility. No return value.

• $main->on_toggle_lockinterface;

  Toggle possibility for user to change Padre's external aspect. No return value.

• $main->on_insert_from_file;

  Prompt user for a file to be inserted at current position in current document. No return value.

• $main->convert_to( $eol_style );

  Convert document to $eol_style line endings (can be one of WIN, UNIX, or MAC). No return value.

• my $editor = $main->find_editor_of_file( $file );

  Return the editor (a Padre::Wx::Editor object) containing the wanted $file, or undef if file is not opened currently.

• my $id = $main->find_id_of_editor( $editor );

  Given $editor, return the tab id holding it, or undef if it was not found.

  Note: can this really work? What happens when we split a window?

• $main->run_in_padre;

  Eval current document within Padre. It means it can access all of Padre's internals, and wreck havoc. Display an error message if the eval went wrong, dump the result in the output panel otherwise.

  No return value.

STC related methods

Those methods are needed to have a smooth STC experience.

• $main->on_stc_style_needed( $event );

  Handler of EVT_STC_STYLENEEDED $event. Used to work around some edge cases in scintilla. No return value.

• $main->on_stc_update_ui;

  Handler called on every movement of the cursor. No return value.

• $main->on_stc_change;

  Handler of the EVT_STC_CHANGE event. Doesn't do anythin. No return value.

• $main->on_stc_char_added;

  This handler is called when a character is added. No return value. See http://www.yellowbrain.com/stc/events.html#EVT_STC_CHARADDED

  TODO: maybe we need to check this more carefully.

• $main->on_stc_dwell_start( $event );

  Handler of the DWELLSTART $event. This event is sent when the mouse has not moved in a given amount of time. Doesn't do anything by now. No return value.

• $main->on_aui_pane_close( $event );

  Handler called upon EVT_AUI_PANE_CLOSE $event. Doesn't do anything by now.

• $main->on_doc_stats;

  Compute various stats about current document, and display them in a message. No return value.

• $main->on_tab_and_space( $style );

  Convert current document from spaces to tabs (or vice-versa) depending on $style (can be either of Space_to_Tab or Tab_to_Space). Prompts the user for how many spaces are to be used to replace tabs (whatever the replacement direction). No return value.

• $main->on_delete_ending_space;

  Trim all ending spaces in current selection, or document if no text is selected. No return value.

• $main->on_delete_leading_space;

  Trim all leading spaces in current selection. No return value.

• $main->timer_check_overwrite;

  Called every n seconds to check if file has been overwritten outside of Padre. If that's the case, prompts the user whether s/he wants to reload the document. No return value.

• $main->on_last_visited_pane;

  Put focus on tab visited before the current one. No return value.

• $main->on_new_from_template( $extension );

  Create a new document according to template for $extension type of file. No return value.

Auxiliary Methods

Various methods that did not fit exactly in above categories...

• $main->install_cpan( $module );

  Install $module from CPAN.

  Note: this method may not belong here...

• $main->setup_bindings;

  Setup the various bindings needed to handle output pane correctly.

  Note: I'm not sure those are really needed...

• $main->set_ppi_highlight( $on );

  Toggle $on the fact that we're using PPI to highlight current Perl document. If not using PPI, we're using syntax highlighting provided by wxSTC.

  Note: this is Perl specific but for now we could not find a better place for this.

• $main->key_up( $event );

  Callback for when a key up $event happens in Padre. This handles the various ctrl+key combinations used within Padre.

COPYRIGHT & LICENSE

Copyright 2008-2009 The Padre development team as listed in Padre.pm.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

cpanm Padre

perl -MCPAN -e shell
install Padre