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)
(Basic Guidelines for Writing a PC-BSD Utility)
Line 84: Line 84:
 
ALT + C = Configure (Main Menu)<br>
 
ALT + C = Configure (Main Menu)<br>
 
ALT + H = Help (Main Menu)
 
ALT + H = Help (Main Menu)
 +
 +
'''Saving Settings in a Qt application'''
 +
 +
When saving an application settings for use between runs, the QSettings class should be used if possible. There are two different "organizations" that should be used however, depending on whether the application is running with root permissions or user permissions. Use "PCBSD" for the organization in an application that runs with user permissions, and "PCBSD-root" for applications that are started up with root permissions via "sudo". This will prevent the directory where those settings files are saved from being locked down by the root applications, allowing the user applications to still be able to save/load their settings files normally.
 +
 +
Example (user application - C++ code):
 +
QSettings settings("PCBSD", "myapplication");
 +
 +
Example 2 (root application - C++ code):
 +
QSettings settings("PCBSD-root", "myapplication");
  
 
== Resources ==
 
== Resources ==

Revision as of 08:09, 28 February 2014


Contents


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.

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.

File Menus

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.

File Configure
Import PBI List Settings
Export PBI List
Quit
Picture 1: AppCafe File Menu

File Menu Icons

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.

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

Buttons

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.

Apply - Applies settings and leaves window open.
Close - Closes program without applying settings
OK - Closes dialogue window and saves settings (i.e. appcafe settings)
Cancel - Closes dialogue window without applying settings
Save - Saves Settings and closes window

Keyboard Shortcuts

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 the user to be able to browse around the file menu, just put &File in the text slot for the menu entry in QT Designer when making your app (or adjusting a current one). Whichever letter has the & symbol in front of it will become a hot key. You can also make a "shortcut" key by clicking the menu or submenu entry and assigning a shortcut key. Make sure 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 accessability. Below is a list of standard shortcut keys.

Shortcut Keys

CTRL + Q = Quit
F1 = Help

Hot Keys (browse by using alt + appropriate letter in submenu)

Q = Quit
S = Settings
I = Import
E = Export
ALT + F = File (Main Menu)
ALT + C = Configure (Main Menu)
ALT + H = Help (Main Menu)

Saving Settings in a Qt application

When saving an application settings for use between runs, the QSettings class should be used if possible. There are two different "organizations" that should be used however, depending on whether the application is running with root permissions or user permissions. Use "PCBSD" for the organization in an application that runs with user permissions, and "PCBSD-root" for applications that are started up with root permissions via "sudo". This will prevent the directory where those settings files are saved from being locked down by the root applications, allowing the user applications to still be able to save/load their settings files normally.

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

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

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 6% • ‎English 100%
Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox