Nav apraksta

thelayoutsystem.tex 8.5KB

1234567891011121314151617181920212223242526272829303132333435363738394041
  1. The layout system is responsible for positioning and scaling layout elements such as axis rects, legends and plot titles in a \hyperlink{class_q_custom_plot}{Q\+Custom\+Plot}.\hypertarget{thelayoutsystem_layoutsystem-classesandmechanisms}{}\section{Classes and mechanisms}\label{thelayoutsystem_layoutsystem-classesandmechanisms}
  2. The layout system is based on the abstract base class \hyperlink{class_q_c_p_layout_element}{Q\+C\+P\+Layout\+Element}. All objects that take part in the layout system derive from this class, either directly or indirectly.
  3. Since \hyperlink{class_q_c_p_layout_element}{Q\+C\+P\+Layout\+Element} itself derives from \hyperlink{class_q_c_p_layerable}{Q\+C\+P\+Layerable}, a layout element may draw its own content. However, it is perfectly possible for a layout element to only serve as a structuring and/or positioning element, not drawing anything on its own.\hypertarget{thelayoutsystem_layoutsystem-rects}{}\subsection{Rects of a layout element}\label{thelayoutsystem_layoutsystem-rects}
  4. A layout element is a rectangular object described by two rects\+: the inner rect (\hyperlink{class_q_c_p_layout_element_affdfea003469aac3d0fac5f4e06171bc}{Q\+C\+P\+Layout\+Element\+::rect}) and the outer rect (\hyperlink{class_q_c_p_layout_element_a38975ea13e36de8e53391ce41d94bc0f}{Q\+C\+P\+Layout\+Element\+::set\+Outer\+Rect}). The inner rect is calculated automatically by applying the margin (\hyperlink{class_q_c_p_layout_element_a8f450b1f3f992ad576fce2c63d8b79cf}{Q\+C\+P\+Layout\+Element\+::set\+Margins}) inward from the outer rect. The inner rect is meant for main content while the margin area may either be left blank or serve for displaying peripheral graphics. For example, \hyperlink{class_q_c_p_axis_rect}{Q\+C\+P\+Axis\+Rect} positions the four main axes at the sides of the inner rect, so graphs end up inside it and the axis labels and tick labels are in the margin area.\hypertarget{thelayoutsystem_layoutsystem-margins}{}\subsection{Margins}\label{thelayoutsystem_layoutsystem-margins}
  5. Each layout element may provide a mechanism to automatically determine its margins. Internally, this is realized with the Q\+C\+P\+Layout\+Element\+::calculate\+Auto\+Margin function which takes a \hyperlink{namespace_q_c_p_a7e487e3e2ccb62ab7771065bab7cae54}{Q\+C\+P\+::\+Margin\+Side} and returns an integer value which represents the ideal margin for the specified side. The automatic margin will be used on the sides specified in \hyperlink{class_q_c_p_layout_element_accfda49994e3e6d51ed14504abf9d27d}{Q\+C\+P\+Layout\+Element\+::set\+Auto\+Margins}. By default, it is set to \hyperlink{namespace_q_c_p_a7e487e3e2ccb62ab7771065bab7cae54a43d7361cb0c5244eabdc962021bffebc}{Q\+C\+P\+::ms\+All} meaning automatic margin calculation is enabled for all four sides. In this case, a minimum margin may be set with \hyperlink{class_q_c_p_layout_element_a0a8a17abc16b7923159fcc7608f94673}{Q\+C\+P\+Layout\+Element\+::set\+Minimum\+Margins}, to prevent the automatic margin mechanism from setting margins smaller than desired for a specific situation. If automatic margin calculation is unset for a specific side, the margin of that side can be controlled directy via \hyperlink{class_q_c_p_layout_element_a8f450b1f3f992ad576fce2c63d8b79cf}{Q\+C\+P\+Layout\+Element\+::set\+Margins}.
  6. If multiple layout ements are arranged next to or beneath each other, it may be desirable to align their inner rects on certain sides. Since they all might have different automatic margins, this usually isn\textquotesingle{}t the case. The class \hyperlink{class_q_c_p_margin_group}{Q\+C\+P\+Margin\+Group} and \hyperlink{class_q_c_p_layout_element_a516e56f76b6bc100e8e71d329866847d}{Q\+C\+P\+Layout\+Element\+::set\+Margin\+Group} fix this by allowing to synchronize multiple margins. See the documentation there for details.\hypertarget{thelayoutsystem_layoutsystem-layout}{}\subsection{Layouts}\label{thelayoutsystem_layoutsystem-layout}
  7. As mentioned, a \hyperlink{class_q_c_p_layout_element}{Q\+C\+P\+Layout\+Element} may have an arbitrary number of child layout elements and in princple can have the only purpose to manage/arrange those child elements. This is what the subclass \hyperlink{class_q_c_p_layout}{Q\+C\+P\+Layout} specializes on. It is a \hyperlink{class_q_c_p_layout_element}{Q\+C\+P\+Layout\+Element} itself but has no visual representation. It defines an interface to add, remove and manage child layout elements. \hyperlink{class_q_c_p_layout}{Q\+C\+P\+Layout} isn\textquotesingle{}t a usable layout though, it\textquotesingle{}s an abstract base class that concrete layouts derive from, like \hyperlink{class_q_c_p_layout_grid}{Q\+C\+P\+Layout\+Grid} which arranges its child elements in a grid and \hyperlink{class_q_c_p_layout_inset}{Q\+C\+P\+Layout\+Inset} which allows placing child elements freely inside its rect.
  8. Since a \hyperlink{class_q_c_p_layout}{Q\+C\+P\+Layout} is a layout element itself, it may be placed inside other layouts. This way, complex hierarchies may be created, offering very flexible arrangements.
  9. Sketch of the default \hyperlink{class_q_c_p_layout_grid}{Q\+C\+P\+Layout\+Grid} accessible via \hyperlink{class_q_custom_plot_afd280d4d621ae64a106543a545c508d7}{Q\+Custom\+Plot\+::plot\+Layout}. The left image shows the outer and inner rect of the grid layout itself while the right image shows how two child layout elements are placed inside the grid layout next to each other in cells (0, 0) and (0, 1). \hypertarget{thelayoutsystem_layoutsystem-plotlayout}{}\subsection{The top level plot layout}\label{thelayoutsystem_layoutsystem-plotlayout}
  10. Every \hyperlink{class_q_custom_plot}{Q\+Custom\+Plot} has one top level layout of type \hyperlink{class_q_c_p_layout_grid}{Q\+C\+P\+Layout\+Grid}. It is accessible via \hyperlink{class_q_custom_plot_afd280d4d621ae64a106543a545c508d7}{Q\+Custom\+Plot\+::plot\+Layout} and contains (directly or indirectly via other sub-\/layouts) all layout elements in the \hyperlink{class_q_custom_plot}{Q\+Custom\+Plot}. By default, this top level grid layout contains a single cell which holds the main axis rect.\hypertarget{thelayoutsystem_layoutsystem-examples}{}\subsection{Examples}\label{thelayoutsystem_layoutsystem-examples}
  11. {\bfseries Adding a plot title} is a typical and simple case to demonstrate basic workings of the layout system.
  12. \begin{DoxyCode}
  13. \textcolor{comment}{// first we create and prepare a plot title layout element:}
  14. \hyperlink{class_q_c_p_plot_title}{QCPPlotTitle} *title = \textcolor{keyword}{new} \hyperlink{class_q_c_p_plot_title}{QCPPlotTitle}(customPlot);
  15. title->\hyperlink{class_q_c_p_plot_title_aae5a93e88050dfb2cbf6adc087516821}{setText}(\textcolor{stringliteral}{"Plot Title Example"});
  16. title->\hyperlink{class_q_c_p_plot_title_a199fc7170802ea65006c371875349e37}{setFont}(QFont(\textcolor{stringliteral}{"sans"}, 12, QFont::Bold));
  17. \textcolor{comment}{// then we add it to the main plot layout:}
  18. customPlot->plotLayout()->insertRow(0); \textcolor{comment}{// insert an empty row above the axis rect}
  19. customPlot->plotLayout()->addElement(0, 0, title); \textcolor{comment}{// insert the title in the empty cell we just created}
  20. \end{DoxyCode}
  21. {\bfseries Arranging multiple axis rects} actually is the central purpose of the layout system.
  22. \begin{DoxyCode}
  23. customPlot->plotLayout()->clear(); \textcolor{comment}{// let's start from scratch and remove the default axis rect}
  24. \textcolor{comment}{// add the first axis rect in second row (row index 1):}
  25. customPlot->plotLayout()->addElement(1, 0, \textcolor{keyword}{new} QCPAxisRect(customPlot));
  26. \textcolor{comment}{// create a sub layout that we'll place in first row:}
  27. \hyperlink{class_q_c_p_layout_grid}{QCPLayoutGrid} *subLayout = \textcolor{keyword}{new} \hyperlink{class_q_c_p_layout_grid}{QCPLayoutGrid};
  28. customPlot->plotLayout()->\hyperlink{class_q_c_p_layout_grid_adff1a2ca691ed83d2d24a4cd1fe17012}{addElement}(0, 0, subLayout);
  29. \textcolor{comment}{// add two axis rects in the sub layout next to eachother:}
  30. subLayout->\hyperlink{class_q_c_p_layout_grid_adff1a2ca691ed83d2d24a4cd1fe17012}{addElement}(0, 0, \textcolor{keyword}{new} QCPAxisRect(customPlot));
  31. subLayout->\hyperlink{class_q_c_p_layout_grid_adff1a2ca691ed83d2d24a4cd1fe17012}{addElement}(0, 1, \textcolor{keyword}{new} QCPAxisRect(customPlot));
  32. subLayout->\hyperlink{class_q_c_p_layout_grid_ae38f31a71687b9d7ee3104852528fb50}{setColumnStretchFactor}(0, 3); \textcolor{comment}{// left axis rect shall have 60% of width}
  33. subLayout->\hyperlink{class_q_c_p_layout_grid_ae38f31a71687b9d7ee3104852528fb50}{setColumnStretchFactor}(1, 2); \textcolor{comment}{// right one only 40% (3:2 = 60:40)}
  34. \end{DoxyCode}