Merge pull request #1 from giorgiomarcias/development

Update to GLFW 3.2

CMakeLists.txt

@@ -11,52 +11,142 @@
 # Author: Giorgio Marcias
 # email: [email protected]
 
-CMAKE_MINIMUM_REQUIRED(VERSION 3.1)
+cmake_minimum_required(VERSION 3.1)
+
+project(glfwm LANGUAGES CXX)
+
+# set current glfwm version
+set(GLFWM_VERSION_MAJOR "3")
+set(GLFWM_VERSION_MINOR "2")
+set(GLFWM_VERSION_PATCH "0")
+set(GLFWM_VERSION_TWEAK "")
+set(GLFWM_VERSION "${GLFWM_VERSION_MAJOR}.${GLFWM_VERSION_MINOR}")
+set(GLFWM_VERSION_FULL "${GLFWM_VERSION}.${GLFWM_VERSION_PATCH}${GLFWM_VERSION_TWEAK}")
+
+# depending on whether this list file is included with add_subdirectory or not, behaviour changes
+get_directory_property(GLFWM_PARENT_DIRECTORY PARENT_DIRECTORY)
+
+
+
+# dependencies:
 
 # GLFW
-SET(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake/Modules ${CMAKE_MODULE_PATH})
-FIND_PACKAGE(GLFW REQUIRED)
-IF(NOT GLFW_FOUND)
-    MESSAGE(FATAL_ERROR "GLFW not found!")
-ENDIF(NOT GLFW_FOUND)
-
-OPTION(WITH_MULTITHREADING "Build GLFWM with multithreading facilities (i.e. thread-safe) or not." ON)
-
-SET(HDR_DIR ${CMAKE_CURRENT_SOURCE_DIR}/include)
-SET(HDRS
-    ${HDR_DIR}/glfwm/common.hpp
-    ${HDR_DIR}/glfwm/drawable.hpp
-    ${HDR_DIR}/glfwm/enums.hpp
-    ${HDR_DIR}/glfwm/event.hpp
-    ${HDR_DIR}/glfwm/event_handler.hpp
-    ${HDR_DIR}/glfwm/update_map.hpp
-    ${HDR_DIR}/glfwm/utility.hpp
-    ${HDR_DIR}/glfwm/window.hpp
-    ${HDR_DIR}/glfwm/window_group.hpp
-    ${HDR_DIR}/glfwm/glfwm.hpp)
-
-SET(SRC_DIR ${CMAKE_CURRENT_SOURCE_DIR}/src)
-SET(SRCS
+find_package(glfw3 3.2 REQUIRED)
+
+
+
+# options:
+
+option(WITH_MULTITHREADING "Build GLFWM with multithreading (i.e. thread-safe) or not." ON)
+
+if(GLFWM_PARENT_DIRECTORY)
+    set(MAKE_SHARED OFF)
+else(GLFWM_PARENT_DIRECTORY)
+    set(MAKE_SHARED ON)
+endif(GLFWM_PARENT_DIRECTORY)
+option(BUILD_SHARED_LIBS "Build GLFWM as a shared library or a static library." ${MAKE_SHARED})
+
+if(GLFWM_PARENT_DIRECTORY)
+    set(MAKE_INSTALL OFF)
+else(GLFWM_PARENT_DIRECTORY)
+    set(MAKE_INSTALL ON)
+endif(GLFWM_PARENT_DIRECTORY)
+option(INSTALL_GLFWM "Specify whether installing GLFWM on the system or not" ${MAKE_INSTALL})
+
+if(NOT GLFWM_PARENT_DIRECTORY AND NOT CMAKE_BUILD_TYPE)
+    set(CMAKE_BUILD_TYPE "Release" CACHE STRING "Choose the type of build, options are: Debug|Release|RelWithDebInfo|MinSizeRel." FORCE)
+endif(NOT GLFWM_PARENT_DIRECTORY AND NOT CMAKE_BUILD_TYPE)
+
+
+# collect source files
+set(HDR_DIR_NAME "GLFWM")
+set(HDR_DIR "${${PROJECT_NAME}_SOURCE_DIR}/include")
+set(HDRS
+    ${HDR_DIR}/${HDR_DIR_NAME}/common.hpp
+    ${HDR_DIR}/${HDR_DIR_NAME}/drawable.hpp
+    ${HDR_DIR}/${HDR_DIR_NAME}/enums.hpp
+    ${HDR_DIR}/${HDR_DIR_NAME}/event.hpp
+    ${HDR_DIR}/${HDR_DIR_NAME}/event_handler.hpp
+    ${HDR_DIR}/${HDR_DIR_NAME}/update_map.hpp
+    ${HDR_DIR}/${HDR_DIR_NAME}/utility.hpp
+    ${HDR_DIR}/${HDR_DIR_NAME}/window.hpp
+    ${HDR_DIR}/${HDR_DIR_NAME}/window_group.hpp
+    ${HDR_DIR}/${HDR_DIR_NAME}/glfwm.hpp)
+
+set(SRC_DIR "${${PROJECT_NAME}_SOURCE_DIR}/src")
+set(SRCS
     ${SRC_DIR}/enums.cpp
     ${SRC_DIR}/event.cpp
     ${SRC_DIR}/update_map.cpp
     ${SRC_DIR}/window.cpp
     ${SRC_DIR}/window_group.cpp
     ${SRC_DIR}/glfwm.cpp)
 
-ADD_LIBRARY(GLFWM ${HDRS} ${SRCS})
 
-SET_TARGET_PROPERTIES(GLFWM PROPERTIES
+
+# create the target library
+add_library(${PROJECT_NAME} ${HDRS} ${SRCS})
+
+
+
+# set target properties:
+
+set_target_properties(${PROJECT_NAME} PROPERTIES
     CXX_STANDARD 11
-    CXX_STANDARD_REQUIRED ON)
-
-TARGET_INCLUDE_DIRECTORIES(GLFWM PUBLIC ${GLFW_INCLUDE_DIRS})
-TARGET_INCLUDE_DIRECTORIES(GLFWM PUBLIC ${HDR_DIR}/glfwm)
-TARGET_LINK_LIBRARIES(GLFWM ${GLFW_LIBRARY_DIRS}/${GLFW_LIBRARIES})
-IF(NOT WITH_MULTITHREADING)
-    TARGET_COMPILE_DEFINITIONS(GLFWM PRIVATE NO_MULTITHREADING)
-ENDIF(NOT WITH_MULTITHREADING)
-
-# expose the directories
-SET(GLFWM_INCLUDE_DIRS ${GLFW_INCLUDE_DIRS} ${HDR_DIR} PARENT_SCOPE)
-SET(GLFWM_LIBRARIES GLFWM PARENT_SCOPE)
+    CXX_STANDARD_REQUIRED ON
+    VERSION ${GLFWM_VERSION}
+    SOVERSION ${GLFWM_VERSION_MAJOR}
+)
+if(NOT GLFWM_PARENT_DIRECTORY)
+    set_target_properties(${PROJECT_NAME} PROPERTIES POSITION_INDEPENDENT_CODE ON)
+endif(NOT GLFWM_PARENT_DIRECTORY)
+
+target_include_directories(${PROJECT_NAME} PRIVATE ${HDR_DIR})
+target_include_directories(${PROJECT_NAME} INTERFACE
+                           $<BUILD_INTERFACE:${HDR_DIR}>
+                           $<INSTALL_INTERFACE:$<INSTALL_PREFIX>/include>
+)
+
+target_link_libraries(${PROJECT_NAME} PUBLIC glfw)
+if(NOT WITH_MULTITHREADING)
+    target_compile_definitions(${PROJECT_NAME} PRIVATE NO_MULTITHREADING)
+endif(NOT WITH_MULTITHREADING)
+
+
+
+# installation directives:
+if(INSTALL_GLFWM)
+    # first, install the target library
+    install(TARGETS ${PROJECT_NAME}
+            EXPORT ${PROJECT_NAME}Targets
+            LIBRARY DESTINATION lib
+            INCLUDES DESTINATION include # this appears in INTERFACE properties when exporting
+    )
+    # install the header files
+    install(DIRECTORY ${HDR_DIR}/${HDR_DIR_NAME} DESTINATION include)
+
+    # set and intall the cmake config files, s.t. consumers can easily find this library locations and properties
+    set(GLFWM_CONFIG_PATH "lib/cmake/${PROJECT_NAME}")
+
+    include(CMakePackageConfigHelpers)
+    configure_package_config_file(cmake/glfwmConfig.cmake.in
+                                  ${PROJECT_NAME}Config.cmake
+                                  INSTALL_DESTINATION "${GLFWM_CONFIG_PATH}"
+                                  NO_CHECK_REQUIRED_COMPONENTS_MACRO
+    )
+    write_basic_package_version_file(${PROJECT_NAME}ConfigVersion.cmake
+                                     VERSION ${GLFWM_VERSION_FULL}
+                                     COMPATIBILITY SameMajorVersion
+    )
+    install(FILES
+            ${${PROJECT_NAME}_BINARY_DIR}/${PROJECT_NAME}Config.cmake
+            ${${PROJECT_NAME}_BINARY_DIR}/${PROJECT_NAME}ConfigVersion.cmake
+            DESTINATION "${GLFWM_CONFIG_PATH}"
+    )
+
+    install(EXPORT ${PROJECT_NAME}Targets
+            DESTINATION ${GLFWM_CONFIG_PATH}
+            FILE ${PROJECT_NAME}Targets.cmake
+            EXPORT_LINK_INTERFACE_LIBRARIES
+    )
+endif(INSTALL_GLFWM)

README.md

@@ -17,25 +17,147 @@ A [GLFW](http://www.glfw.org) C++ wrapper with additional OOP features.
 * update notifications to whole groups
 * automatic control of the loop
 
+
+
 ### Compilation
-To compile this software, import it in another software through cmake.
-Supposing to have your software root cmake file at
+#### Dependencies
+There are two mandatory dependencies.
+
+* [GLFW](http://www.glfw.org), which must have already been installed on the system.
+See [http://www.glfw.org](http://www.glfw.org) for details.
+Alternatively, it is possible to get GLFW through package managers, such as apt-get (Linux) or MacPort/Homebrew (Mac OS).
+
+* [cmake](https://cmake.org), which is used to compile and install this library, greatly simplifying this tasks.
+See [https://cmake.org](https://cmake.org) for details.
+Alternatively, as before, it is possible to get cmake through package managers.
+
+
+
+#### Building
+Through *cmake* it is possible to compile and eventually import this library into another software.
+There are two ways to do that.
+
+* *install* the shared library binaries somewhere on the system and then import it:
+
+        mkdir glfwm_build
+        cd glfwm_build
+        cmake <path-to-glfwm>
+        make
+        make install
+
+    Now `glfwm` is installed as a shared library depending on the value of `CMAKE_INSTALL_PREFIX` and can be linked to.
+    Then in the cmake list file `CMakeList.txt` of another project just add:
+
+        ...
+        find_package(glfwm 3.2 REQUIRED)
+        ...
+        add_executable(myexe myexe.cpp)
+        target_link_libraries(myexe glfwm)
+
+    And that's all.
+
+* *include* the library sources in a cmake list file `CMakeList.txt` of another project:
+
+        ...
+        add_subdirectory(<path-to-glfwm> ${${PROJECT_NAME}_BINARY_DIR}/glfwm)
+        ...
+        add_executable(myexe myexe.cpp)
+        target_link_libraries(myexe glfwm)
+
+    In this way, `glfwm` is compiled as a static library in the build tree of the `myexe` target.
+
+##### Build options
+There are some options that affect the compilation and/or installation:
+
+* `WITH_MULTITHREADING` enables/disables multi-threading support. This allows windows to operate and be managed in separate threads.
+
+* `BUILD_SHARED_LIBS` makes `glfwm` be built as a shared (if `ON`) or a static (if `OFF`) library.
+
+* `INSTALL_GLFWM` makes `glfwm` be installed (if `ON`) or not (if `OFF`).
 
-    <path-to-your-software>/CMakeLists.txt
+Default values mainly depends on the way it is built as described in the **Building** section above.
+`BUILD_SHARED_LIBS` and `INSTALL_GLFWM` are `OFF` when glfwm is included as a sub-directory, `ON` otherwise.
+`WITH_MULTITHREADING` is always `ON`.
 
-add GLFWM as subdirectory to it:
+It is possible to change these options either as argument to the `cmake` command, e.g. `-DWITH_MULTITHREADING=OFF`, or directly in the cmake list file of another project which includes glfwm:
 
-    # uncomment the following line if you do NOT want multi-threading support
-    #SET(WITH_MULTITHREADING OFF CACHE BOOL "Build GLFWM with multithreading facilities (i.e. thread-safe) or not.")
-    ADD_SUBDIRECTORY(<path-to-glfwm> ${CMAKE_CURRENT_BINARY_DIR}/glfwm)
     ...
-    TARGET_INCLUDE_DIRECTORIES(${PROJECT_NAME} PUBLIC ${GLFWM_INCLUDE_DIRS})
-    TARGET_LINK_LIBRARIES(${PROJECT_NAME} ${GLFWM_LIBRARIES})
+    option(WITH_MULTITHREADING "Build GLFWM with multithreading (i.e. thread-safe) or not." OFF)
+    add_subdirectory(<path-to-glfwm> ${${PROJECT_NAME}_BINARY_DIR}/glfwm)
+    ...
+
+### Usage
+The main purpose is to manage windows.
+So the main objects are `Window`s and a `WindowManager` which takes care of.
+
+First of all, include the main header:
+
+    #include <GLFWM/glfwm.hpp>
+
+Then initialize the library resources by calling
+
+    glfwm::WindowManager::init();
+
+at the beginning of the program execution, e.g. in the `main` function before everything.
+
+A `Window` can receive events and draw some content.
+For this purpose, special objects can bind to it.
+
+Derive `EventHandler` and override the `getHandledEventTypes()` and `handle()` methods in order to react to events like cursor position changes and mouse button clicks.
+Then bind such objects to a `Window` s.t. events directed to it may handled:
+
+    class MyHandler : public glfwm::EventHandler {
+        public:
+        glfwm::EventBaseType getHandledEventTypes() const override
+        {
+            return static_cast<glfwm::EventBaseType>(glfwm::EventType::MOUSE_BUTTON);
+        }
+
+        bool handle(const glfwm::EventPointer &e) override
+        {
+            if (e->getEventType() == glfwm::EventType::MOUSE_BUTTON) {
+                // make some action based on this event
+                ...
+                return true;
+            }
+            return false;
+        }
+    };
+
+Derive `Drawable` and override the `draw()` method.
+There put the code responsible of drawing the content, e.g. OpenGL calls:
+
+    class MyDrawable : public glfwm::Drawable {
+        public:
+        void draw(const glfwm::WindowID id) override
+        {
+            // draw the content on the screen
+        }
+    };
+
+Then create some `Window` and bind the handler and the drawable to it:
+
+    std::shared_ptr<MyHandler> myHandler = std::make_shared<MyHandler>();
+    std::shared_ptr<MyDrawable> myDrawable = std::make_shared<MyDrawable>();
+    glfwm::WindowPointer mainWin = glfwm::WindowManager::createWindow(800, 600, std::string(), myHandler->getHandledEventTypes());
+    mainWin->bindEventHandler(myHandler, 0);    // 0 is the rank among all event handlers bound
+    mainWin->bindDrawable(myDrawable, 0);       // 0 is the rank among all drawables bound
+
+Possibly create other windows and group them.
+Groups are usefull for concurrent management (i.e. multi-threaded windows) or even just for sending notifications to all the windows in the same group.
+Notifications can be used to make several windows react to a single event.
+To create a group and attach windows:
+
+    glfwm::WindowGroupPointer grp = glfwm::WindowGroup::newGroup();
+    grp->attachWindow(mainWin->getID());
+    grp->runLoopConcurrently();     // this is available only if compiled with WITH_MULTITHREADING=ON
+
+Finally, start the main loop, which ends when all the windows are closed, and release the library resources:
 
-Then it can be compiled with the commands:
+    glfwm::WindowManager::mainLoop();
+    glfwm::WindowManager::terminate();
 
-    > cmake <path-to-your-software>
-    > make
+See the examples for more details.
 
 It has been tested on Mac OS X 10.9 - 10.10 - 10.11
 

cmake/glfwmConfig.cmake.in

@@ -0,0 +1,4 @@
+include(CMakeFindDependencyMacro)
+find_dependency(glfw3 3.2)
+
+include("${CMAKE_CURRENT_LIST_DIR}/glfwmTargets.cmake")