Documentation for most of the Widget Panel.

fluid/autodoc.cxx

@@ -18,9 +18,11 @@
 
 #include "autodoc.h"
 #include "fluid.h"
+#include "factory.h"
 #include "widget_browser.h"
 #include "widget_panel.h"
 #include "Fl_Widget_Type.h"
+#include "Fl_Window_Type.h"
 #include "function_panel.h"
 
 #include <FL/Enumerations.H>
@@ -350,12 +352,22 @@ int fl_snapshot(const char *filename, Fl_Widget *w,
 void run_autodoc(const Fl_String &target_dir) {
   Fl_Margin win_margin(0, 0, 0, 0);
   Fl_Margin win_blend(10, 10, 10, 10);
-
-  the_panel = make_widget_panel();
-  // fl_snapshot(target_dir + "data_panel.png", widget_x_input, widget_h_input,
-  //              Fl_Margin(FL_SNAP_TO_WINDOW, 4, FL_SNAP_TO_WINDOW, 4),
-  //              Fl_Margin(0, 10, 0, 10));
-  // fl_open_uri(("file://" + target_dir + "data_panel.png").c_str());
+  Fl_Margin tab_margin(FL_SNAP_TO_WINDOW, 32, FL_SNAP_TO_WINDOW, 4);
+  Fl_Margin xrow_margin(FL_SNAP_TO_WINDOW, 14, FL_SNAP_TO_WINDOW, 4);
+  Fl_Margin row_margin(FL_SNAP_TO_WINDOW, 4, FL_SNAP_TO_WINDOW, 4);
+  Fl_Margin row_blend(0, 10, 0, 10);
+
+  new_project(false);
+  Fl_Type *t_func = add_new_widget_from_user("Function", kAddAsLastChild, false);
+  Fl_Window_Type *t_win = (Fl_Window_Type*)add_new_widget_from_user("Fl_Window", kAddAsLastChild, false);
+  t_win->label("My Main Window");
+  Fl_Type *t_grp = add_new_widget_from_user("Fl_Group", kAddAsLastChild, false);
+  Fl_Widget_Type *t_btn = (Fl_Widget_Type*)add_new_widget_from_user("Fl_Button", kAddAsLastChild, false);
+  ((Fl_Button*)t_btn->o)->shortcut(FL_COMMAND|'g');
+  Fl_Type *t_sldr = add_new_widget_from_user("Fl_Slider", kAddAsLastChild, false);
+  Fl_Type *t_inp = add_new_widget_from_user("Fl_Input", kAddAsLastChild, false);
+  widget_browser->rebuild();
+  g_project.update_settings_dialog();
 
   // TODO: take a snapshot of FLUID in a desktop situation
   // (main, toolbar, document, widget editor, source view)
@@ -392,44 +404,99 @@ void run_autodoc(const Fl_String &target_dir) {
   f_name_input->value("count_trees(const char *forest_name)");
   f_return_type_input->value("unsigned int");
   fl_snapshot((target_dir + "function_panel.png").c_str(), adoc_function_panel, win_margin, win_blend);
+  adoc_function_panel->hide();
   // - ID_Code
   Fl_Window *adoc_code_panel = make_code_panel();
   code_input->buffer()->text("// increment user count\nif (new_user) {\n  user_count++;\n}\n");
   fl_snapshot((target_dir + "code_panel.png").c_str(), adoc_code_panel, win_margin, win_blend);
+  adoc_code_panel->hide();
   // - ID_CodeBlock
   Fl_Window *adoc_codeblock_panel = make_codeblock_panel();
   code_before_input->value("if (test())");
   code_after_input->value("// test widgets added...");
   fl_snapshot((target_dir + "codeblock_panel.png").c_str(), adoc_codeblock_panel, win_margin, win_blend);
+  adoc_codeblock_panel->hide();
   // - ID_Decl
   Fl_Window *adoc_decl_panel = make_decl_panel();
   decl_class_choice->hide();
   decl_input->buffer()->text("const char *damage = \"'tis but a scratch\";");
   fl_snapshot((target_dir + "decl_panel.png").c_str(), adoc_decl_panel, win_margin, win_blend);
+  adoc_decl_panel->hide();
   // - ID_DeclBlock
   Fl_Window *adoc_declblock_panel = make_declblock_panel();
   decl_before_input->value("#ifdef NDEBUG");
   decl_after_input->value("#endif // NDEBUG");
   fl_snapshot((target_dir + "declblock_panel.png").c_str(), adoc_declblock_panel, win_margin, win_blend);
+  adoc_declblock_panel->hide();
   // - ID_Class
   Fl_Window *adoc_class_panel = make_class_panel();
   decl_class_choice->hide();
   c_name_input->value("Zoo_Giraffe");
   c_subclass_input->value("Zoo_Animal");
   fl_snapshot((target_dir + "class_panel.png").c_str(), adoc_class_panel, win_margin, win_blend);
+  adoc_class_panel->hide();
   // - ID_Widget_Class is handled like Fl_Window_Type
   // - ID_Comment
   Fl_Window *adoc_comment_panel = make_comment_panel();
   comment_input->buffer()->text("Make sure that the giraffe gets enough hay,\nbut the monkey can't reach it.");
   fl_snapshot((target_dir + "comment_panel.png").c_str(), adoc_comment_panel, win_margin, win_blend);
+  adoc_comment_panel->hide();
   // - ID_Data
   Fl_Window *adoc_data_panel = make_data_panel();
   data_class_choice->hide();
   data_input->value("emulated_ROM");
   data_filename->value("./ROM.bin");
   fl_snapshot((target_dir + "data_panel.png").c_str(), adoc_data_panel, win_margin, win_blend);
+  adoc_data_panel->hide();
 
   // TODO: widget dialog
+  t_win->open(); // open the window
+  t_win->open(); // open the panel
+  select_only(t_win);
+
+  // snapshot of the widget properties panel
+  fl_snapshot((target_dir + "widget_panel.png").c_str(), the_panel, win_margin, win_blend);
+
+  // snapshot of the GUI tab
+  fl_snapshot((target_dir + "wp_gui_label.png").c_str(), wp_gui_label, tab_margin, row_blend);
+  select_only(t_btn);
+  fl_snapshot((target_dir + "wp_gui_image.png").c_str(), widget_image_input, widget_deimage_input, row_margin, row_blend);
+  fl_snapshot((target_dir + "wp_gui_alignment.png").c_str(), wp_gui_alignment, row_margin, row_blend);
+  fl_snapshot((target_dir + "wp_gui_size.png").c_str(), widget_x_input, xrow_margin, row_blend);
+  select_only(t_sldr);
+  fl_snapshot((target_dir + "wp_gui_values.png").c_str(), wp_gui_values, xrow_margin, row_blend);
+  select_only(t_win);
+  fl_snapshot((target_dir + "wp_gui_sizerange.png").c_str(), wp_gui_sizerange, xrow_margin, row_blend);
+  select_only(t_btn);
+  fl_snapshot((target_dir + "wp_gui_shortcut.png").c_str(), wp_gui_shortcut, row_margin, row_blend);
+  select_only(t_win);
+  fl_snapshot((target_dir + "wp_gui_xclass.png").c_str(), wp_gui_xclass, row_margin, row_blend);
+  select_only(t_btn);
+  fl_snapshot((target_dir + "wp_gui_attributes.png").c_str(), wp_gui_attributes, row_margin, row_blend);
+  fl_snapshot((target_dir + "wp_gui_tooltip.png").c_str(), wp_gui_tooltip, row_margin, row_blend);
+
+  // snapshot of the style tab
+  widget_tabs->value(wp_style_tab);
+  select_only(t_inp);
+  fl_snapshot((target_dir + "wp_style_tab.png").c_str(), wp_style_tab, tab_margin, row_blend);
+  fl_snapshot((target_dir + "wp_style_label.png").c_str(), wp_style_label, row_margin, row_blend);
+  select_only(t_btn);
+  fl_snapshot((target_dir + "wp_style_box.png").c_str(), wp_style_box, wp_style_downbox, row_margin, row_blend);
+  select_only(t_inp);
+  fl_snapshot((target_dir + "wp_style_text.png").c_str(), wp_style_text, row_margin, row_blend);
+
+  // snapshot of the C++ tab
+  widget_tabs->value(wp_cpp_tab);
+  select_only(t_btn);
+  fl_snapshot((target_dir + "wp_cpp_tab.png").c_str(), wp_cpp_tab, tab_margin, row_blend);
+  fl_snapshot((target_dir + "wp_cpp_class.png").c_str(), wp_cpp_class, row_margin, row_blend);
+  fl_snapshot((target_dir + "wp_cpp_name.png").c_str(), wp_cpp_name, row_margin, row_blend);
+  fl_snapshot((target_dir + "v_input.png").c_str(), v_input[0], v_input[3], row_margin, row_blend);
+  fl_snapshot((target_dir + "wComment.png").c_str(), wComment, row_margin, row_blend);
+  fl_snapshot((target_dir + "wp_cpp_callback.png").c_str(), wCallback, w_when_box, row_margin, row_blend);
+
+  //  fl_open_uri(("file://" + target_dir + "test.png").c_str());
+
   // overview, multiple selection, instand feedback
   // individual standard tabs
   // list of special tabs for Grid

fluid/documentation/src/page_appendices.dox

@@ -4,6 +4,244 @@
 
  \tableofcontents
 
+ \section appendix_app_widget Widget Properties Panel
+
+ ## The Widget Properties Panel ##
+
+ \image html widget_panel.png "Widget Properties"
+ \image latex widget_panel.png "Widget Properties"
+
+ This panel is used to edit the properties of one or more selected widgets in
+ the widget tree. Depending on the widget selection, some properties may
+ be grayed out or may be invisible.
+
+ The panel has three standard tabs that apply to all widgets. Some widget
+ type, `Fl_Grid` and children of `Fl_Grid` for example, will create additional
+ tabs with more options.
+
+ <!-- ---------------------------------------------------------------------- -->
+ ## The GUI Tab ##
+
+ This tab controls basic GUI settings, including label text and widget size.
+
+ \image html wp_gui_label.png
+ \image latex wp_gui_label.png
+
+ The *Label* field can be any Unicode string and is stored as a static text.
+ If internationalization is enabled, the corresponding modifiers are
+ added. Labels can span multiple lines by pressing `Ctrl-J` to insert a new-line
+ character.
+
+ The `@` character adds a symbol to the label. See *"Labels and Label Types"*
+ in the FLTK documentation.
+
+ The pulldown menu offers some additional rendering styles for the label.
+
+ \image html wp_gui_image.png
+ \image latex wp_gui_image.png
+
+ Add an image to the widget label here. The second row takes an optional image
+ for rendering a deactivated widget.
+
+ The image path must be relative to the location of the `.fl` file.
+ The image data is inlined into the source code. If *compressed* is selected
+ in the image properties field, the image is stored in its original format, and
+ the fltk-images library must be linked to decompress at runtime.
+
+ Images are stored at their original resolution. The image properties dialog
+ provides *Scale* settings to scaled the image before rendering to screen.
+ To make full use of high-dpi screen support, images should be stored at double
+ resolution and then scaled to FLTK coordinates. This gives FLTK the chance to
+ fall back to the full size image for high-dpi screens.
+
+ \image html wp_gui_alignment.png
+ \image latex wp_gui_alignment.png
+
+ Control alignment of the label in relation to the widget position and size as
+ well as the relation between the image and the label. The box on the right
+ toggles between inside and outside label alignment.
+
+ \image html wp_gui_size.png
+ \image latex wp_gui_size.png
+
+ Control the size and position of a widget here. The input fields react to
+ vertical scroll wheel input for interactive positioning.
+
+ All fields understand basic math. They are evaluated after the formula is
+ entered and the result is stored in the respective properties. Formulas can
+ also contain a number of variables. The *x* input can handle the variables
+ `x` for its own position, `px` for the parent position, `sx` for the previous
+ sibling, `cx` for the leftmost x position of all children, and `i`, which is a
+ counter through all selected widgets.
+
+ The formula `x+10` in the *x* field moves all selected widgets 10 pixels to
+ the right. `100+25*i` arranges all widgets vertically starting at 100 with
+ 25 pixels distance.
+
+ \todo Fl_Flex parent
+
+ \image html wp_gui_values.png
+ \image latex wp_gui_values.png
+
+ Activate for widgets that can take numerical values, these input fields take
+ floating point numbers. The generate lines like `o->minimum(2);` only if the
+ corresponding value differs from the default value for this property.
+
+ \image html wp_gui_sizerange.png
+ \image latex wp_gui_sizerange.png
+
+ This group is only visible for top level windows. The field sets the minimum
+ and maximum size range for windows. Use the *set* button to copy the current
+ size. Set width and height to `0` to disable that aspect of the size range.
+
+ \todo Fl_Flex margins
+
+ \image html wp_gui_shortcut.png
+ \image latex wp_gui_shortcut.png
+
+ This option is only visible for buttons and other widgets that can react to a
+ shortcut key combination. FLUID does not check if a shortcut was already used
+ elsewhere.
+
+ If *shortcut use FL_COMMAND* is set in the project settings, modifiers are
+ created in a more compatible way across platforms.
+
+ \image html wp_gui_xclass.png
+ \image latex wp_gui_xclass.png
+
+ This group is only visible for top level windows. Note that selecting *modal*
+ and *non modal* together is undefined.
+
+ \image html wp_gui_attributes.png
+ \image latex wp_gui_attributes.png
+
+ Some additional attributes for all widget types. Activating *resizable* will
+ add code to the parent widget to make this widget the resizable one of the
+ parent group. Activating *hotspot* will add code to the parent window to make
+ this widget the hotspot widget.
+
+ \image html wp_gui_tooltip.png
+ \image latex wp_gui_tooltip.png
+
+ The *Tooltip* field can be any Unicode string and is stored as a static text.
+ If internationalization is enabled, the corresponding modifiers are
+ added.
+
+ <!-- ---------------------------------------------------------------------- -->
+ ## The Style Tab ##
+
+ \image html wp_style_tab.png
+ \image latex wp_style_tab.png
+
+ The Style tab is used to edit font styles and size, and the color of elements
+ of the widget.
+
+ \image html wp_style_label.png
+ \image latex wp_style_label.png
+
+ \image html wp_style_text.png
+ \image latex wp_style_text.png
+
+ The font pulldown menu provides a list of standard fonts. To enter the index
+ of a user loaded font, an *extra code* field must be used. The *label color*
+ and *text color* fields opens a color palette selector. The arrow pulldown
+ contains a list of the most commonly used colors. Again, user specific colors
+ can be defined using the *extra code* field.
+
+ The *Text Font* row is only available for widgets that contain an addition
+ text area.
+
+ \image html wp_style_box.png
+ \image latex wp_style_box.png
+
+ Select the up and down box for the give widget. The first six entries in the
+ box and frame style list are influenced by the FLTK Scheme setting. Other
+ box styles will always look the same, independently of the selected scheme.
+
+ The *Down Box* row is only available for widgets that can be pressed down
+ by the user.
+
+ <!-- ---------------------------------------------------------------------- -->
+ ## The C++ Tab ##
+
+ \image html wp_cpp_tab.png
+ \image latex wp_cpp_tab.png
+
+ The C++ tab has various input field for adding C++ code at various places
+ in the source and header file.
+
+ \image html wp_cpp_class.png
+ \image latex wp_cpp_class.png
+
+ If the class property is set, FLUID assumes that the user wants to instantiate
+ a widget that is derived from the selected widget. For a derived widget, the
+ default values of attribute can not be known. FLUID will generate code to
+ explicitly set every know attribute of the super class.
+
+ If the selected widget is a Widget Class node, the Class property will instead
+ set the super class of the widget.
+
+ The pulldown menu on the right side contain additional subtypes for some
+ widget types. `Fl_Button` widgets, for instance, can be further refined to
+ be an `Fl_Toggle_Button` of an `Fl_Radio_Button`.
+
+ \image html wp_cpp_name.png
+ \image latex wp_cpp_name.png
+
+ The name field can be any valid C++ variable name. If the widget is inside
+ a class, the pulldown menu lets the user select between *private*, *protected*,
+ and *public*. If not in the group, the variable can be *global* or *static*
+ within the source file.
+
+ \image html v_input.png
+ \image latex v_input.png
+
+ These four input fields can be used to add arbitrary code to different parts
+ of the header and source file. A line can be divided into multiple lines
+ of code by inserting a `Ctrl-J`.
+
+ All Extra Code fields are interpreted individually. If a field contains a `#`
+ character, or the words `extern`, `typedef`, or `using`, FLUID assumes that
+ the code is a declaration and writes it to the header file, and only if it
+ does not duplicate previously written code. This is great for creating a
+ `#include "MyWidgetType.H"` include statement in the header.
+
+ If the code is not recognized as a declaration, it will instead be put after
+ the code that instantiates the widget and all its children. For menu items,
+ the code is added after the container  `Fl_Menu_` is created, but before the
+ menu array is added to the container.
+
+ \image html wComment.png
+ \image latex wComment.png
+
+ Comments are added to the source code before the widget constructor by adding
+ `// ` in front of every line of the comment. The first few characters of a
+ comment are also visible in the widget browser in the main window.
+
+ \image html wp_cpp_callback.png
+ \image latex wp_cpp_callback.png
+
+ The callback field can be interpreted in two ways. If the callback text is only
+ a single word, FLUID assumes that this is the name of an external callback
+ function and declares it in the header as
+ `extern void my_button_action(Fl_Button*, void*);`.
+
+ Otherwise, FLUID assumes that the text is the body of a C++ callback function
+ and instead creates a local callback function. The name of the callback
+ function is generated by FLUID and guaranteed to be unique within the file.
+ ```
+ static void cb_input(Fl_Input*, void*) {
+   ... // my text from the Callback field here
+ }
+ ```
+
+ *User Data* can be any valid C++ code and is copied as the callback argument.
+ *Type* is currently limited to `void*` and `long`. The *When* pulldown gives
+ access to the `Fl_When` flags, including some commonly used combinations.
+
+ <!-- ---------------------------------------------------------------------- -->
+ <!-- ---------------------------------------------------------------------- -->
+
  \section appendix_code_nodes Functional Node Types
 
  ## Functions and Methods ##
@@ -380,7 +618,7 @@
  \image latex comment_panel.png "Comment Properties"
 
  Comment blocks are generated by adding `// ` to the start of each line unless
- the first line of a comment starts with `/*`. In that case, FLUID assumes
+ the first line of a comment starts with `/``*`. In that case, FLUID assumes
  a correct block comment and will copy the text verbatim.
 
  Comments can be generated in the header file, the source file, or both.