juce/source/src/core/juce_PlatformUtilities.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_PLATFORMUTILITIES_JUCEHEADER__
  27 #define __JUCE_PLATFORMUTILITIES_JUCEHEADER__
  28
  29 #include "../text/juce_StringArray.h"
  30 #include "../io/files/juce_File.h"
  31
  32
  33 //==============================================================================
  34 /**
  35     A collection of miscellaneous platform-specific utilities.
  36
  37 */
  38 class JUCE_API  PlatformUtilities
  39 {
  40 public:
  41     //==============================================================================
  42     /** Plays the operating system's default alert 'beep' sound. */
  43     static void beep();
  44
  45     /** Tries to launch the system's default reader for a given file or URL. */
  46     static bool openDocument (const String& documentURL, const String& parameters);
  47
  48     /** Tries to launch the system's default email app to let the user create an email.
  49     */
  50     static bool launchEmailWithAttachments (const String& targetEmailAddress,
  51                                             const String& emailSubject,
  52                                             const String& bodyText,
  53                                             const StringArray& filesToAttach);
  54
  55 #if JUCE_MAC || JUCE_IOS || DOXYGEN
  56     //==============================================================================
  57     /** MAC ONLY - Turns a Core CF String into a juce one. */
  58     static String cfStringToJuceString (CFStringRef cfString);
  59
  60     /** MAC ONLY - Turns a juce string into a Core CF one. */
  61     static CFStringRef juceStringToCFString (const String& s);
  62
  63     /** MAC ONLY - Turns a file path into an FSRef, returning true if it succeeds. */
  64     static bool makeFSRefFromPath (FSRef* destFSRef, const String& path);
  65
  66     /** MAC ONLY - Turns an FSRef into a juce string path. */
  67     static String makePathFromFSRef (FSRef* file);
  68
  69     /** MAC ONLY - Converts any decomposed unicode characters in a string into
  70         their precomposed equivalents.
  71     */
  72     static String convertToPrecomposedUnicode (const String& s);
  73
  74     /** MAC ONLY - Gets the type of a file from the file's resources. */
  75     static OSType getTypeOfFile (const String& filename);
  76
  77     /** MAC ONLY - Returns true if this file is actually a bundle. */
  78     static bool isBundle (const String& filename);
  79
  80     /** MAC ONLY - Adds an item to the dock */
  81     static void addItemToDock (const File& file);
  82
  83     /** MAC ONLY - Returns the current OS version number.
  84         E.g. if it's running on 10.4, this will be 4, 10.5 will return 5, etc.
  85     */
  86     static int getOSXMinorVersionNumber();
  87 #endif
  88
  89
  90 #if JUCE_WINDOWS || DOXYGEN
  91     //==============================================================================
  92     // Some registry helper functions:
  93
  94     /** WIN32 ONLY - Returns a string from the registry.
  95
  96         The path is a string for the entire path of a value in the registry,
  97         e.g. "HKEY_CURRENT_USER\Software\foo\bar"
  98     */
  99     static String getRegistryValue (const String& regValuePath,
 100                                     const String& defaultValue = String::empty);
 101
 102     /** WIN32 ONLY - Sets a registry value as a string.
 103
 104         This will take care of creating any groups needed to get to the given
 105         registry value.
 106     */
 107     static void setRegistryValue (const String& regValuePath,
 108                                   const String& value);
 109
 110     /** WIN32 ONLY - Returns true if the given value exists in the registry. */
 111     static bool registryValueExists (const String& regValuePath);
 112
 113     /** WIN32 ONLY - Deletes a registry value. */
 114     static void deleteRegistryValue (const String& regValuePath);
 115
 116     /** WIN32 ONLY - Deletes a registry key (which is registry-talk for 'folder'). */
 117     static void deleteRegistryKey (const String& regKeyPath);
 118
 119     /** WIN32 ONLY - Creates a file association in the registry.
 120
 121         This lets you set the exe that should be launched by a given file extension.
 122         @param fileExtension        the file extension to associate, including the
 123                                     initial dot, e.g. ".txt"
 124         @param symbolicDescription  a space-free short token to identify the file type
 125         @param fullDescription      a human-readable description of the file type
 126         @param targetExecutable     the executable that should be launched
 127         @param iconResourceNumber   the icon that gets displayed for the file type will be
 128                                     found by looking up this resource number in the
 129                                     executable. Pass 0 here to not use an icon
 130     */
 131     static void registerFileAssociation (const String& fileExtension,
 132                                          const String& symbolicDescription,
 133                                          const String& fullDescription,
 134                                          const File& targetExecutable,
 135                                          int iconResourceNumber);
 136
 137     /** WIN32 ONLY - This returns the HINSTANCE of the current module.
 138
 139         In a normal Juce application this will be set to the module handle
 140         of the application executable.
 141
 142         If you're writing a DLL using Juce and plan to use any Juce messaging or
 143         windows, you'll need to make sure you use the setCurrentModuleInstanceHandle()
 144         to set the correct module handle in your DllMain() function, because
 145         the win32 system relies on the correct instance handle when opening windows.
 146     */
 147     static void* JUCE_CALLTYPE getCurrentModuleInstanceHandle() noexcept;
 148
 149     /** WIN32 ONLY - Sets a new module handle to be used by the library.
 150
 151         @see getCurrentModuleInstanceHandle()
 152     */
 153     static void JUCE_CALLTYPE setCurrentModuleInstanceHandle (void* newHandle) noexcept;
 154
 155     /** WIN32 ONLY - Gets the command-line params as a string.
 156
 157         This is needed to avoid unicode problems with the argc type params.
 158     */
 159     static String JUCE_CALLTYPE getCurrentCommandLineParams();
 160 #endif
 161
 162     /** Clears the floating point unit's flags.
 163
 164         Only has an effect under win32, currently.
 165     */
 166     static void fpuReset();
 167
 168
 169 #if JUCE_LINUX || JUCE_WINDOWS
 170     //==============================================================================
 171     /** Loads a dynamically-linked library into the process's address space.
 172
 173         @param pathOrFilename   the platform-dependent name and search path
 174         @returns                a handle which can be used by getProcedureEntryPoint(), or
 175                                 zero if it fails.
 176         @see freeDynamicLibrary, getProcedureEntryPoint
 177     */
 178     static void* loadDynamicLibrary (const String& pathOrFilename);
 179
 180     /** Frees a dynamically-linked library.
 181
 182         @param libraryHandle   a handle created by loadDynamicLibrary
 183         @see loadDynamicLibrary, getProcedureEntryPoint
 184     */
 185     static void freeDynamicLibrary (void* libraryHandle);
 186
 187     /** Finds a procedure call in a dynamically-linked library.
 188
 189         @param libraryHandle    a library handle returned by loadDynamicLibrary
 190         @param procedureName    the name of the procedure call to try to load
 191         @returns                a pointer to the function if found, or 0 if it fails
 192         @see loadDynamicLibrary
 193     */
 194     static void* getProcedureEntryPoint (void* libraryHandle,
 195                                          const String& procedureName);
 196 #endif
 197
 198 private:
 199     PlatformUtilities();
 200
 201     JUCE_DECLARE_NON_COPYABLE (PlatformUtilities);
 202 };
 203
 204
 205 //==============================================================================
 206 #if JUCE_MAC || JUCE_IOS || DOXYGEN
 207
 208  /** A handy C++ wrapper that creates and deletes an NSAutoreleasePool object using RAII. */
 209  class JUCE_API  ScopedAutoReleasePool
 210  {
 211  public:
 212      ScopedAutoReleasePool();
 213      ~ScopedAutoReleasePool();
 214
 215  private:
 216      void* pool;
 217
 218      JUCE_DECLARE_NON_COPYABLE (ScopedAutoReleasePool);
 219  };
 220
 221  /** A macro that can be used to easily declare a local ScopedAutoReleasePool object for RAII-based obj-C autoreleasing. */
 222  #define JUCE_AUTORELEASEPOOL  const JUCE_NAMESPACE::ScopedAutoReleasePool JUCE_JOIN_MACRO (autoReleasePool_, __LINE__);
 223
 224 #else
 225  #define JUCE_AUTORELEASEPOOL
 226 #endif
 227
 228
 229 //==============================================================================
 230 #if JUCE_LINUX
 231
 232 /** A handy class that uses XLockDisplay and XUnlockDisplay to lock the X server
 233     using an RAII approach.
 234 */
 235 class ScopedXLock
 236 {
 237 public:
 238     /** Creating a ScopedXLock object locks the X display.
 239         This uses XLockDisplay() to grab the display that Juce is using.
 240     */
 241     ScopedXLock();
 242
 243     /** Deleting a ScopedXLock object unlocks the X display.
 244         This calls XUnlockDisplay() to release the lock.
 245     */
 246     ~ScopedXLock();
 247 };
 248
 249 #endif
 250
 251
 252 //==============================================================================
 253 #if JUCE_MAC
 254
 255 /**
 256     A wrapper class for picking up events from an Apple IR remote control device.
 257
 258     To use it, just create a subclass of this class, implementing the buttonPressed()
 259     callback, then call start() and stop() to start or stop receiving events.
 260 */
 261 class JUCE_API  AppleRemoteDevice
 262 {
 263 public:
 264     //==============================================================================
 265     AppleRemoteDevice();
 266     virtual ~AppleRemoteDevice();
 267
 268     //==============================================================================
 269     /** The set of buttons that may be pressed.
 270         @see buttonPressed
 271     */
 272     enum ButtonType
 273     {
 274         menuButton = 0,     /**< The menu button (if it's held for a short time). */
 275         playButton,         /**< The play button. */
 276         plusButton,         /**< The plus or volume-up button. */
 277         minusButton,        /**< The minus or volume-down button. */
 278         rightButton,        /**< The right button (if it's held for a short time). */
 279         leftButton,         /**< The left button (if it's held for a short time). */
 280         rightButton_Long,   /**< The right button (if it's held for a long time). */
 281         leftButton_Long,    /**< The menu button (if it's held for a long time). */
 282         menuButton_Long,    /**< The menu button (if it's held for a long time). */
 283         playButtonSleepMode,
 284         switched
 285     };
 286
 287     //==============================================================================
 288     /** Override this method to receive the callback about a button press.
 289
 290         The callback will happen on the application's message thread.
 291
 292         Some buttons trigger matching up and down events, in which the isDown parameter
 293         will be true and then false. Others only send a single event when the
 294         button is pressed.
 295     */
 296     virtual void buttonPressed (ButtonType buttonId, bool isDown) = 0;
 297
 298     //==============================================================================
 299     /** Starts the device running and responding to events.
 300
 301         Returns true if it managed to open the device.
 302
 303         @param inExclusiveMode  if true, the remote will be grabbed exclusively for this app,
 304                                 and will not be available to any other part of the system. If
 305                                 false, it will be shared with other apps.
 306         @see stop
 307     */
 308     bool start (bool inExclusiveMode);
 309
 310     /** Stops the device running.
 311         @see start
 312     */
 313     void stop();
 314
 315     /** Returns true if the device has been started successfully.
 316     */
 317     bool isActive() const;
 318
 319     /** Returns the ID number of the remote, if it has sent one.
 320     */
 321     int getRemoteId() const                     { return remoteId; }
 322
 323     //==============================================================================
 324     /** @internal */
 325     void handleCallbackInternal();
 326
 327 private:
 328     void* device;
 329     void* queue;
 330     int remoteId;
 331
 332     bool open (bool openInExclusiveMode);
 333
 334     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (AppleRemoteDevice);
 335 };
 336
 337 #endif
 338
 339
 340 #endif   // __JUCE_PLATFORMUTILITIES_JUCEHEADER__