Difference between revisions of "Become a Developer/10.1"

From PC-BSD Wiki
Jump to: navigation, search
(Marked this version for translation)
 
(2 intermediate revisions by one user 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® [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.
 
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.
  
Line 11: Line 10:
 
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-->
== Getting the Source Code and Development Tools ==
+
  
 +
<!--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.
 
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.
  
 +
<!--T:11-->
 
To download the source code, '''cd''' to the directory to store the source and type:
 
To download the source code, '''cd''' to the directory to store the source and type:
  
 +
<!--T:12-->
 
'''git clone <nowiki>git://github.com/pcbsd/pcbsd.git</nowiki>'''
 
'''git clone <nowiki>git://github.com/pcbsd/pcbsd.git</nowiki>'''
  
 +
<!--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.
 
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.
  
 +
<!--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 "pcbsd-toolchain" PBI using '''pbi_add'''.
 
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 "pcbsd-toolchain" PBI using '''pbi_add'''.
  
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.
+
<!--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'''.
  
== Basic Guidelines for Writing a PC‑BSD® Utility ==  
+
== 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.   
 
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.
 
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 ===
+
=== 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.   
 
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''']]     
 
[[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.
 
"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 ===
+
=== 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.
 
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
 
'''Table 11.3a: Commonly Used File Menu Icons
  
 +
<!--T:25-->
 
{| class="spiffy_table"
 
{| class="spiffy_table"
 
|-
 
|-
Line 60: Line 71:
 
|}
 
|}
  
=== Buttons ===
+
=== Buttons === <!--T:26-->
  
 +
<!--T:27-->
 
PC‑BSD® utilities use these buttons as follows:  
 
PC‑BSD® utilities use these buttons as follows:  
  
 +
<!--T:28-->
 
* '''Apply:''' applies settings and leaves the window open.
 
* '''Apply:''' applies settings and leaves the window open.
  
 +
<!--T:29-->
 
* '''Close:''' closes program without applying settings.
 
* '''Close:''' closes program without applying settings.
  
 +
<!--T:30-->
 
* '''OK:''' closes dialogue window and saves settings.
 
* '''OK:''' closes dialogue window and saves settings.
  
 +
<!--T:31-->
 
* '''Cancel:''' closes dialogue window without applying settings.
 
* '''Cancel:''' closes dialogue window without applying settings.
  
 +
<!--T:32-->
 
* '''Save:''' saves settings and closes window.
 
* '''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]].
 
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 ===
+
=== Keyboard Shortcuts === <!--T:34-->
  
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 in Qt Designer 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: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'''
 
'''Table 11.3b: Shortcut Keys'''
  
 +
<!--T:37-->
 
{| class="spiffy_table"
 
{| class="spiffy_table"
 
|-
 
|-
Line 95: Line 116:
 
|}
 
|}
  
 +
<!--T:38-->
 
'''Table 11.3c: Hot Keys'''  
 
'''Table 11.3c: Hot Keys'''  
  
 +
<!--T:39-->
 
{| class="spiffy_table"
 
{| class="spiffy_table"
 
|-
 
|-
Line 125: Line 148:
 
|}
 
|}
  
=== Saving Settings in a Qt Application ===
+
=== Saving Settings in a Qt Application === <!--T:40-->
  
 +
<!--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.
 
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.
  
 +
<!--T:42-->
 
'''Example 11.3a: User Permission Settings'''
 
'''Example 11.3a: User Permission Settings'''
 
{{txtbox|box=(user application - C++ code):
 
{{txtbox|box=(user application - C++ code):
 
QSettings settings("PCBSD", "myapplication");}}
 
QSettings settings("PCBSD", "myapplication");}}
  
 +
<!--T:43-->
 
'''Example 11.3b: Root Permission Settings'''  
 
'''Example 11.3b: Root Permission Settings'''  
 
{{txtbox|box=(root application - C++ code):
 
{{txtbox|box=(root application - C++ code):
 
QSettings settings("PCBSD-root", "myapplication");}}
 
QSettings settings("PCBSD-root", "myapplication");}}
  
== Resources ==
+
== Resources == <!--T:44-->
  
 
<!--T:4-->
 
<!--T:4-->

Latest revision as of 10:08, 16 June 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® 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.

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 "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:

References


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