diff --git a/docs/developer_guide/index.rst b/docs/developer_guide/index.rst new file mode 100644 index 0000000000..d1d3ed8856 --- /dev/null +++ b/docs/developer_guide/index.rst @@ -0,0 +1,21 @@ +.. _developer_guide: + +Scopy overview for developers +================================================================================ + +About +--------------------------------------------------------------------- +Tutorials, coding guidelines and guides for developers. + +.. note:: + + These guides are for Scopy v2.0.0 and future versions. + Follow the user guide for building Scopy an your local machine. Linux is recommended for development + +Source code +--------------------------------------------------------------------- + +The source code for the entire application can be found on `github +`_ + + diff --git a/docs/developer_guide/style.rst b/docs/developer_guide/style.rst new file mode 100644 index 0000000000..b70eef36fb --- /dev/null +++ b/docs/developer_guide/style.rst @@ -0,0 +1,61 @@ +.. _style: + +Style Tutorial +============== + +**Style previewer tool is located in the test plugin** + +Create New Style Property +------------------------- + +Before creating a new style, check if you can use an already existing one or combine multiple existing styles. Only create a new one if necessary. + +Navigate to ``style/qss/properties`` and pick/create a folder that matches the widget type you want to create a property for. Inside the folder, create a ``.qss`` file. + +- All style code must be surrounded by ``{}`` and have a set property ``*[&&property&&=true]{ }``. Do not replace the property name; keep it as ``&&property&&``. +- The property value can be changed from ``true``, but when using it in the application, you also need to specify the correct value. +- Use keys from the JSON files as much as possible. Example: ``&unit_1&``. + +Run CMake, and the new property should appear in ``style_properties.h`` with the same name as the ``.qss`` file. + +Add JSON Value +-------------- + +JSON files should rarely be altered in any way. + +- **Global value:** Add a new key and value in ``style/json/global.json``. +- **Theme value:** Add a new key and value in ``style/json/dark.json`` and all other theme JSON files accordingly. + +Run CMake, and you should find the new value in ``style_attributes.h``. + +Add Theme +--------- + +Add a new ``.json`` file in ``style/json``. + +- Add at least all the values from ``dark.json``. +- Other values from ``global.json`` can be overwritten in the new theme. Example: + "unit_1": "20" (where "unit_1":"16" is in global.json) + +- Properties can also be overwritten. Example: + "qss_properties_button_borderButton": "qss_properties_button_basicButton" + +Add Plugin Style +---------------- + +Create a ``style`` folder in your plugin and use the exact same file structure. Only the ``qss`` folder is relevant since the JSON files cannot be overwritten from other plugins. You may add a folder in your ``style/qss/properties`` folder with the name of your plugin to avoid overwriting other core ``.qss`` style files with the same name. + +In your plugin ``CMakeLists.txt`` file, add the ``generate_style`` command. + +**Arguments:** ``option, style_folder, header_folder`` (option should always be ``--plugin``). + +Example: + +.. code-block:: cmake + + include(ScopyStyle) + generate_style("--plugin" ${CMAKE_CURRENT_SOURCE_DIR}/style ${CMAKE_CURRENT_SOURCE_DIR}/include/pluginName) + +Run CMake, and you should see the new properties in ``header_folder/style_properties.h``. + + diff --git a/docs/index.rst b/docs/index.rst index 775dac3d49..ce1ddcf029 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -32,3 +32,6 @@ Contents user_guide/preferences user_guide/bugReport user_guide/troubleshooting + + + developer_guide/style diff --git a/gui/style/README.md b/gui/style/README.md deleted file mode 100644 index 9ab98b3f41..0000000000 --- a/gui/style/README.md +++ /dev/null @@ -1,37 +0,0 @@ -# Style tutorial -**Style previewer tool is located in the test plugin** - -## Create new style property - -Before creating a new style check if you can use an already existing or combine multiple existing styles. Only create a new one if necessary. - -Navigate to style/qss/properties and pick/create a folder which matches the widget type you want to create a property for. Inside the folder create a .qss file. -- all style code must be surrounded by {} and have set a property "*[&&property&&=true]{ }". Do not replace the property name, keep it "&&property&&" -- property value can be changed from "true", but when using it in application you also need to specify the correct value -- use keys from the json files as much as possible. example: &unit_1& - -Run CMake and the new property should appear in style_properties.h with the same name as the .qss file. - -## Add json value -Json files should rarely be altered in any way. -global value: add new key and value in style/json/global.json -theme value: add new key and value in style/json/dark.json and all other theme jsons accordingly -Run CMake and you should find the new value in style_attributes.h. - -## Add theme -Add new .json file in style/json. -- add at least all the values from dark.json -- other values from global.json can be overwritten in the new theme. example: "unit_1": "20" (where "unit_1":"16" is in global.json ) -- properties can also be overwritten. example: "qss_properties_button_borderButton": "qss_properties_button_basicButton" - -## Add plugin style -Create a style folder in your plugin and use the exact same file structure. Only the qss folder is relevant since the json files cannot be overwritten from other plugins. You may add a folder in your style/qss/properties folder with the name of your plugin to avoid overwriting other core .qss style files with the same name. -In your plugin CMakeLists.txt file add the generate_style command. -arguments: **option, style_folder, header_folder** (option should always be "--plugin") - -example: -**include(ScopyStyle) -generate_style("--plugin" ${CMAKE_CURRENT_SOURCE_DIR}/style ${CMAKE_CURRENT_SOURCE_DIR}/include/pluginName)** - -Run CMake and you should see the new properties in header_folder/style_properties.h. -