Difference between revisions of "Become a Developer/10.1"

From PC-BSD Wiki
Jump to: navigation, search
(Basic Guidelines for Writing a PC-BSD Utility)
 
(28 intermediate revisions by 3 users not shown)
Line 4: Line 4:
 
{{UseTOC{{putVers}}|Nav}}</noinclude>
 
{{UseTOC{{putVers}}|Nav}}</noinclude>
  
<!--T:2-->
+
== Introduction == <!--T:2-->
== Introduction ==
+
If you like programming, and especially coding on FreeBSD, we would love to see you join the PC-BSD® Team as a PC-BSD® committer. Developers who want to help improve the PC-BSD® codebase are always welcome! If you would like to participate in core development, subscribe to the {{citelink|pcbsdlists|url=dev|txt=developers mailing list}}. Once you have signed up, feel free to browse the active tickets in the PC-BSD® [https://bugs.pcbsd.org/projects/pcbsd/ Bug database]. If you see something that you want to work on, or have a proposal for a project you wish to add to PC-BSD®, please let us know via the developers list and we will be happy to help get you started.
If you like programming, and especially coding on FreeBSD, we would love to see you join the PC-BSD® Team as a PC-BSD® committer. Developers who want to help improve the PC-BSD® codebase are always welcome! If you would like to participate in core development, subscribe to the {{citelink|pcbsdlists|url=dev|txt=developers mailing list}}. Once you have signed up, feel free to browse the active tickets in the PC-BSD® [http://trac.pcbsd.org/report Trac database]. If you see something that you want to work on, or have a proposal for a project you wish to add to PC-BSD®, please let us know via the developers list and we will be happy to help get you started.
+
  
 
<!--T:3-->
 
<!--T:3-->
Most of the PC-BSD® specific GUI tools are developed in C++ using the QT Libraries, and other non-GUI development is done using standard Bourne shell scripts. There may be cases where other languages or libraries are needed, but those will be evaluated on a case-by-case basis, so feel free to let us know your proposals on the developers mailing list.
+
Most of the PC-BSD® specific GUI tools are developed in C++ using the Qt Libraries, and other non-GUI development is done using standard Bourne shell scripts. There may be cases where other languages or libraries are needed, but those will be evaluated on a case-by-case basis, so feel free to let us know your proposals on the developers mailing list.
  
<!--T:3.1-->
+
== Getting the Source Code and Development Tools == <!--T:3.1-->
== Basic Guidelines for Writing a PC-BSD Utility ==
+
  
PC-BSD is a community driven project that relies on the support of developers in the community to help in the design and implementation of new utilities and tools for PC-BSD. Going forward we want to make sure to present a somewhat unified design so that the programs feel "familiar" to users that are using them. As an example some programs may have "File", "Main", or "System" as their first entry on the "file menu", but instead we want to present one option which would be "File".  Below you will find a small list of guidelines to file menu's and program design in PC-BSD.
+
<!--T:10-->
 +
The PC‑BSD® source code is available from github and '''git''' needs to be installed in order to download the source code. When using PC‑BSD®, '''git''' is included in the base install.
  
'''File Menus'''
+
<!--T:11-->
 +
To download the source code, '''cd''' to the directory to store the source and type:
  
Any program that is a "full featured utility" (i.e. warden, appcafe) should have a file menu.  File menus are of course not necessary for small widget programs or dialogue boxes.  When making a file menu a good rule of thumb is keep it simple! Most (not all) PC-BSD utilities don't need more than 2 or 3 categories on the file menu bar. A good example of a well laid out menu is the AppCafe.  File (although non-descriptive) is the accepted norm for the first category on the menu bar.  Since most programs designed for the last couple of decades have followed this structure it makes sense for us to follow the same standard.  Configure is our adopted standard for the category that wil contain "settings" or other configuration related settings.  If additional categories are needed try to see if another PC-BSD utility uses the same or similar category so we do not duplicate categories that are technically the same.
+
<!--T:12-->
 +
'''git clone <nowiki>git://github.com/pcbsd/pcbsd.git</nowiki>'''
  
{| class="spiffy_table"
+
<!--T:13-->
|-
+
This will create a directory named ''pcbsd/'' which contains the local copy of the repository. To keep the local copy in sync with the official repository, run '''git pull''' within the ''pcbsd'' directory.
! File
+
! Configure
+
|-
+
| Import PBI List
+
| Settings
+
|-
+
| Export PBI List
+
|
+
|-
+
| Quit
+
|
+
|}
+
  
[[file:AppCafe_File_menu.png|thumb|393px|'''Picture 1: AppCafe File Menu''']]
+
<!--T:14-->
 +
PC‑BSD® graphical applications use Qt version 4 and their source is located in ''pcbsd/src-qt4/''. In order to compile the applications in this directory, install the "PC-BSD Build ToolChain" PBI using {{local|link=AppCafe®}}. To instead install this PBI from the command line, install the "devel/pcbsd-toolchain" PBI using '''pbi add'''.
  
'''File Menu Icons'''
+
<!--T:15-->
 +
Several Qt IDEs are available in {{local|link=AppCafe®}}. The "[http://qt-project.org/wiki/Category:Tools::QtCreator QtCreator]" PBI is a full featured IDE designed to help new Qt users get up and running faster while boosting the productivity of experienced Qt developers. [http://qt-project.org/doc/qt-4.8/designer-manual.html Qt Designer] is lighter weight as it is only a ''.ui'' file editor and does not provide any other IDE functionality. It can be installed as the "qt4-designer" raw package using {{local|link=AppCafe®}} or '''pkg install'''.
  
File menu icons are taken from the KDE "Oxygen" theme located in /usr/local/share/icons/oxygen.  For the same reasons as file menus, file menu icons should try and follow the same standards so we don't have a bunch of different icons floating around for the exact same or similar function.  Below is a list of commonly used icons and their default file names.
+
== Basic Guidelines for Writing a PC‑BSD® Utility == <!--T:16-->
  
 +
<!--T:17-->
 +
PC‑BSD® is a community driven project that relies on the support of developers in the community to help in the design and implementation of new utilities and tools for PC‑BSD®. Going forward, we aim to present a unified design so that programs feel "familiar" to users. As an example, while programs could have "File", "Main", or "System" as their first entry on the "File menu", we want to present one option, "File", as it is the accepted norm for the first category on the menu bar. 
 +
 +
<!--T:18-->
 +
This section describes a small list of guidelines to menu and program design in PC‑BSD®. Since most programs designed for the last couple of decades have followed this structure, it makes sense for us to follow the same standard.
 +
 +
=== File Menus === <!--T:19-->
 +
 +
<!--T:20-->
 +
Any graphical program that is a full-featured utility, such as Warden® or AppCafe®, should have a file menu.  However, file menus are not necessary for small widget programs or dialogue boxes.  When making a file menu, a good rule of thumb is keep it simple.  Most PC‑BSD® utilities do not need more than two or three items on the file menu.  An example of a well laid out "File" menu is AppCafe®, shown in Figure 11.3a. 
 +
[[file:Filemenu.png|thumb|393px|'''Figure 11.3a: AppCafe® File Menu''']]   
 +
 +
<!--T:21-->
 +
"Configure" is our adopted standard for the category that contains "Settings" or other configuration related settings.  If additional categories are needed, check to see what other PC‑BSD® utilities are using.
 +
 +
=== File Menu Icons === <!--T:22-->
 +
 +
<!--T:23-->
 +
File menu icons are taken from the KDE "Oxygen" theme located in ''/usr/local/share/icons/oxygen''. Use these file menu icons so we do not have a bunch of different icons used for the same function.  Table 11.3a lists the commonly used icons and their default file names.
 +
 +
<!--T:24-->
 +
'''Table 11.3a: Commonly Used File Menu Icons
 +
 +
<!--T:25-->
 
{| class="spiffy_table"
 
{| class="spiffy_table"
 
|-
 
|-
Line 56: Line 71:
 
|}
 
|}
  
'''Buttons'''
+
=== Buttons === <!--T:26-->
  
There may be some confusion over the "role" of buttons.  The list below shows some of the more common buttons and their general "roles" in PC-BSD Utilities. For fully functional programs like the AppCafe or Warden we want to steer away from having close buttons on the front of the application.  Basically if there is a file menu, that and an x in the top right will suffice.  Dialogues and widget programs are exceptions to this rule.  A good example of a widget program would be Upgrade Manager.
+
<!--T:27-->
 +
PC‑BSD® utilities use these buttons as follows:
 +
 
 +
<!--T:28-->
 +
* '''Apply:''' applies settings and leaves the window open.
 +
 
 +
<!--T:29-->
 +
* '''Close:''' closes program without applying settings.
 +
 
 +
<!--T:30-->
 +
* '''OK:''' closes dialogue window and saves settings.
 +
 
 +
<!--T:31-->
 +
* '''Cancel:''' closes dialogue window without applying settings.
 +
 
 +
<!--T:32-->
 +
* '''Save:''' saves settings and closes window.
 +
 
 +
<!--T:33-->
 +
Fully functional programs like [[AppCafe®/10.1|AppCafe®]] and [[Warden®/10.1|Warden®]] do not use close buttons on the front of the application.  Basically, whenever there is a "File" menu, that and an x in the top right corner of the application are used instead.  Dialogues and widget programs are exceptions to this rule.  A good example of a widget program would be [[Update Manager/10.1|Update Manager]].
 +
 
 +
=== Keyboard Shortcuts === <!--T:34-->
 +
 
 +
<!--T:35-->
 +
Many users benefit from keyboard shortcuts and we aim to make them available in every PC‑BSD® utility.  Qt makes it easy to assign keyboard shortcuts.  For instance, to configure keyboard shortcuts that browse the "File" menu, put ''&File'' in the text slot for the menu entry when making the application.  Whichever letter has the & symbol in front of it will become the hot key.  You can also make a shortcut key by clicking the menu or submenu entry and assigning a shortcut key.  Be careful not to duplicate hot keys or shortcut keys.  Every key in a menu and submenu should have a key assigned for ease of use and accessibility.  Tables 11.3b and 11.3c summarize the commonly used shortcut and hot keys.
 +
 
 +
<!--T:36-->
 +
'''Table 11.3b: Shortcut Keys'''
 +
 
 +
<!--T:37-->
 +
{| class="spiffy_table"
 +
|-
 +
! Shortcut Key
 +
! Action
 +
|-
 +
|CTRL + Q
 +
|Quit
 +
|-
 +
|F1
 +
|Help
 +
|-
 +
|}
 +
 
 +
<!--T:38-->
 +
'''Table 11.3c: Hot Keys'''
 +
 
 +
<!--T:39-->
 +
{| class="spiffy_table"
 +
|-
 +
! Hot Key
 +
! Action
 +
|-
 +
|Alt + Q
 +
|Quit
 +
|-
 +
|Alt + S
 +
|Settings
 +
|-
 +
|Alt + I
 +
|Import
 +
|-
 +
|Alt + E
 +
|Export
 +
|-
 +
|ALT + F
 +
|File Menu
 +
|-
 +
|ALT + C
 +
|Configure Menu
 +
|-
 +
|ALT + H
 +
|Help Menu
 +
|-
 +
|}
  
'''Apply'''  - Applies settings and leaves window open. <br>
+
=== Saving Settings in a Qt Application === <!--T:40-->
'''Close'''  - Closes program without applying settings <br>
+
'''OK'''    - Closes dialogue window and saves settings (i.e. appcafe settings) <br>
+
'''Cancel''' - Closes dialogue window without applying settings <br>
+
'''Save'''  - Saves Settings and closes window <br>
+
  
'''Keyboard Shortcuts'''
+
<!--T:41-->
 +
When saving an application's settings, the QSettings class should be used if possible. There are two different "organizations", depending on whether the application is running with root permissions or user permissions. Use "PCBSD" for the organization for applications that run with user permissions and "PCBSD-root" for applications that are started with root permissions via '''sudo'''. Proper use prevents the directory where settings files are saved from being locked down by root applications, allowing user applications to save and load their settings. Examples 11.3a and 11.3b demonstrate how to use the QSettings class for each type of permission.
  
Many users benefit from keyboard shortcuts and we'd like them to be available in every PC-BSD utility. When assigning keyboard shortcuts QT makes it super easy!  For instance if you want to make Ctrl + Q the default to "Quit" the program, just put &Quit in the bolded text slot in QT Designer when making your app (or adjusting a current one).  Whichever letter has the & symbol in front of it will become the shortcut key.  Make sure not to duplicate shortcut keys!  Every key in a menu and submenu should have a shortcut key assigned for ease of use and accessability.  Below is a list of standard shortcut keys.
+
<!--T:42-->
 +
'''Example 11.3a: User Permission Settings'''
 +
{{txtbox|box=(user application - C++ code):
 +
QSettings settings("PCBSD", "myapplication");}}
  
CTRL + Q = Quit<br>
+
<!--T:43-->
CTRL + S = Settings<br>
+
'''Example 11.3b: Root Permission Settings'''
CTRL + I = Import<br>
+
{{txtbox|box=(root application - C++ code):
CTRL + E = Export<br>
+
QSettings settings("PCBSD-root", "myapplication");}}
CTRL + F = File (Main Menu)<br>
+
CTRL + C = Configure (Main Menu)<br>
+
F1 = Help
+
  
== Resources ==
+
== Resources == <!--T:44-->
  
 
<!--T:4-->
 
<!--T:4-->

Latest revision as of 14:08, 14 October 2014


Contents


[edit] Introduction

If you like programming, and especially coding on FreeBSD, we would love to see you join the PC-BSD® Team as a PC-BSD® committer. Developers who want to help improve the PC-BSD® codebase are always welcome! If you would like to participate in core development, subscribe to the developers mailing list[1]. Once you have signed up, feel free to browse the active tickets in the PC-BSD® Bug database. If you see something that you want to work on, or have a proposal for a project you wish to add to PC-BSD®, please let us know via the developers list and we will be happy to help get you started.

Most of the PC-BSD® specific GUI tools are developed in C++ using the Qt Libraries, and other non-GUI development is done using standard Bourne shell scripts. There may be cases where other languages or libraries are needed, but those will be evaluated on a case-by-case basis, so feel free to let us know your proposals on the developers mailing list.

[edit] Getting the Source Code and Development Tools

The PC‑BSD® source code is available from github and git needs to be installed in order to download the source code. When using PC‑BSD®, git is included in the base install.

To download the source code, cd to the directory to store the source and type:

git clone git://github.com/pcbsd/pcbsd.git

This will create a directory named pcbsd/ which contains the local copy of the repository. To keep the local copy in sync with the official repository, run git pull within the pcbsd directory.

PC‑BSD® graphical applications use Qt version 4 and their source is located in pcbsd/src-qt4/. In order to compile the applications in this directory, install the "PC-BSD Build ToolChain" PBI using AppCafe®. To instead install this PBI from the command line, install the "devel/pcbsd-toolchain" PBI using pbi add.

Several Qt IDEs are available in AppCafe®. The "QtCreator" PBI is a full featured IDE designed to help new Qt users get up and running faster while boosting the productivity of experienced Qt developers. Qt Designer is lighter weight as it is only a .ui file editor and does not provide any other IDE functionality. It can be installed as the "qt4-designer" raw package using AppCafe® or pkg install.

[edit] Basic Guidelines for Writing a PC‑BSD® Utility

PC‑BSD® is a community driven project that relies on the support of developers in the community to help in the design and implementation of new utilities and tools for PC‑BSD®. Going forward, we aim to present a unified design so that programs feel "familiar" to users. As an example, while programs could have "File", "Main", or "System" as their first entry on the "File menu", we want to present one option, "File", as it is the accepted norm for the first category on the menu bar.

This section describes a small list of guidelines to menu and program design in PC‑BSD®. Since most programs designed for the last couple of decades have followed this structure, it makes sense for us to follow the same standard.

[edit] File Menus

Any graphical program that is a full-featured utility, such as Warden® or AppCafe®, should have a file menu. However, file menus are not necessary for small widget programs or dialogue boxes. When making a file menu, a good rule of thumb is keep it simple. Most PC‑BSD® utilities do not need more than two or three items on the file menu. An example of a well laid out "File" menu is AppCafe®, shown in Figure 11.3a.

Figure 11.3a: AppCafe® File Menu

"Configure" is our adopted standard for the category that contains "Settings" or other configuration related settings. If additional categories are needed, check to see what other PC‑BSD® utilities are using.

[edit] File Menu Icons

File menu icons are taken from the KDE "Oxygen" theme located in /usr/local/share/icons/oxygen. Use these file menu icons so we do not have a bunch of different icons used for the same function. Table 11.3a lists the commonly used icons and their default file names.

Table 11.3a: Commonly Used File Menu Icons

Function File Menu Icon File Name
Quit row 1, cell 2 window-close.png
Settings row 2, cell 2 configure.png

[edit] Buttons

PC‑BSD® utilities use these buttons as follows:

  • Apply: applies settings and leaves the window open.
  • Close: closes program without applying settings.
  • OK: closes dialogue window and saves settings.
  • Cancel: closes dialogue window without applying settings.
  • Save: saves settings and closes window.

Fully functional programs like AppCafe® and Warden® do not use close buttons on the front of the application. Basically, whenever there is a "File" menu, that and an x in the top right corner of the application are used instead. Dialogues and widget programs are exceptions to this rule. A good example of a widget program would be Update Manager.

[edit] Keyboard Shortcuts

Many users benefit from keyboard shortcuts and we aim to make them available in every PC‑BSD® utility. Qt makes it easy to assign keyboard shortcuts. For instance, to configure keyboard shortcuts that browse the "File" menu, put &File in the text slot for the menu entry when making the application. Whichever letter has the & symbol in front of it will become the hot key. You can also make a shortcut key by clicking the menu or submenu entry and assigning a shortcut key. Be careful not to duplicate hot keys or shortcut keys. Every key in a menu and submenu should have a key assigned for ease of use and accessibility. Tables 11.3b and 11.3c summarize the commonly used shortcut and hot keys.

Table 11.3b: Shortcut Keys

Shortcut Key Action
CTRL + Q Quit
F1 Help

Table 11.3c: Hot Keys

Hot Key Action
Alt + Q Quit
Alt + S Settings
Alt + I Import
Alt + E Export
ALT + F File Menu
ALT + C Configure Menu
ALT + H Help Menu

[edit] Saving Settings in a Qt Application

When saving an application's settings, the QSettings class should be used if possible. There are two different "organizations", depending on whether the application is running with root permissions or user permissions. Use "PCBSD" for the organization for applications that run with user permissions and "PCBSD-root" for applications that are started with root permissions via sudo. Proper use prevents the directory where settings files are saved from being locked down by root applications, allowing user applications to save and load their settings. Examples 11.3a and 11.3b demonstrate how to use the QSettings class for each type of permission.

Example 11.3a: User Permission Settings

(user application - C++ code): QSettings settings("PCBSD", "myapplication");

Example 11.3b: Root Permission Settings

(root application - C++ code): QSettings settings("PCBSD-root", "myapplication");

[edit] Resources

Developers will also find the following resources helpful:

  • [GettingSource Getting started with PC-BSD® Source - Building, forking and committing][2]

References


  1. http://lists.pcbsd.org/mailman/listinfo/dev
  2. GettingSource
  3. http://lists.pcbsd.org/mailman/listinfo/commits
  4. http://doc.qt.digia.com/4.7/qmake-manual.html
Other languages:German 7% • ‎English 100%